Moving folders
This commit is contained in:
Chris Smith
189
README.md
189
README.md
@@ -1,161 +1,68 @@
|
||||
# list thingy API
|
||||
# List Thingy
|
||||
|
||||
A list thingy API using plain PHP for shopping, todos, or other lists. Users create a list instantly without any signup.
|
||||
They will get a UUID and can share it with friends and collaborate on lists. This API will manage the list with API
|
||||
calls and will also run a websocket the iOS and Android apps can connect to.
|
||||
A collaborative list management platform for shopping, todos, and other lists. Create lists instantly without signup, share with friends via UUID, and collaborate in real-time.
|
||||
|
||||
## Philosophy
|
||||
|
||||
- No accounts
|
||||
- No ads
|
||||
- No bloat
|
||||
- Code that just works for 15 years
|
||||
|
||||
## API
|
||||
## Project Structure
|
||||
|
||||
This monorepo contains three components:
|
||||
|
||||
### [API](./api)
|
||||
Pure PHP REST API with SQLite database. Handles all list and item operations with WebSocket support for real-time collaboration.
|
||||
|
||||
**Tech Stack:**
|
||||
- Pure PHP 8.0+ (no frameworks)
|
||||
- SQLite with PDO
|
||||
- Custom PSR-4 autoloader
|
||||
- .env configuration
|
||||
|
||||
[See API documentation →](./api/README.md)
|
||||
|
||||
## Quick Start
|
||||
|
||||
### API Server
|
||||
|
||||
```bash
|
||||
cd api
|
||||
cp .env.example .env
|
||||
cd public
|
||||
php -S localhost:8000
|
||||
```
|
||||
|
||||
### Mobile Apps
|
||||
|
||||
Coming soon
|
||||
|
||||
## Features
|
||||
|
||||
- Create lists without signup
|
||||
- Share lists via UUID
|
||||
- Collaborative editing
|
||||
- Real-time updates (WebSocket)
|
||||
- Optimistic update and save
|
||||
- Categorized items
|
||||
- Quantity tracking
|
||||
- Soft delete (items)
|
||||
|
||||
## API Endpoints
|
||||
|
||||
#### Lists
|
||||
|
||||
- POST /list
|
||||
- GET /list/{uuid}
|
||||
- PATCH /list/{uuid}
|
||||
- DELETE /list/{uuid}
|
||||
|
||||
#### Items
|
||||
|
||||
- POST /list/{uuid}/item
|
||||
- PATCH /list/{uuid}/item/{id}
|
||||
- DELETE /list/{uuid}/item/{id}
|
||||
|
||||
## Setup
|
||||
## License
|
||||
|
||||
### Requirements
|
||||
|
||||
- PHP 8.0 or higher
|
||||
- SQLite3 extension (usually included with PHP)
|
||||
|
||||
### Installation
|
||||
|
||||
1. Clone the repository
|
||||
2. Copy `.env.example` to `.env`:
|
||||
|
||||
```bash
|
||||
cp .env.example .env
|
||||
```
|
||||
|
||||
3. (Optional) Edit `.env` to customize configuration
|
||||
4. Start the PHP development server:
|
||||
|
||||
```bash
|
||||
cd public
|
||||
php -S localhost:8000
|
||||
```
|
||||
|
||||
The database will be automatically created on first request at `db/database.sqlite`.
|
||||
|
||||
### Configuration
|
||||
|
||||
All configuration is managed through the `.env` file:
|
||||
|
||||
- `DB_PATH` - Path to SQLite database file (relative or absolute)
|
||||
- `CORS_ALLOW_ORIGIN` - CORS allowed origins (default: `*`)
|
||||
- `CORS_ALLOW_METHODS` - CORS allowed HTTP methods
|
||||
- `CORS_ALLOW_HEADERS` - CORS allowed headers
|
||||
- `ERROR_REPORTING` - Enable/disable error reporting (true/false)
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### Create a List
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:8000/list \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"name":"Shopping List","sharable":true}'
|
||||
```
|
||||
|
||||
Response:
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"id": 1,
|
||||
"uuid": "a1b2c3d4e5f6...",
|
||||
"name": "Shopping List",
|
||||
"sharable": true,
|
||||
"created_at": "2025-12-12 12:00:00"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Get a List with Items
|
||||
|
||||
```bash
|
||||
curl http://localhost:8000/list/{uuid}
|
||||
```
|
||||
|
||||
### Update a List
|
||||
|
||||
```bash
|
||||
curl -X PATCH http://localhost:8000/list/{uuid} \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"name":"Updated List Name"}'
|
||||
```
|
||||
|
||||
### Delete a List
|
||||
|
||||
```bash
|
||||
curl -X DELETE http://localhost:8000/list/{uuid}
|
||||
```
|
||||
|
||||
### Add Item to List
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:8000/list/{uuid}/item \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"name":"Milk","quantity":2.5,"category":"Dairy"}'
|
||||
```
|
||||
|
||||
### Update Item
|
||||
|
||||
```bash
|
||||
curl -X PATCH http://localhost:8000/list/{uuid}/item/{id} \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"quantity":3}'
|
||||
```
|
||||
|
||||
### Delete Item (Soft Delete)
|
||||
|
||||
```bash
|
||||
curl -X DELETE http://localhost:8000/list/{uuid}/item/{id}
|
||||
```
|
||||
|
||||
## Models
|
||||
|
||||
#### List Model
|
||||
|
||||
- id
|
||||
- uuid
|
||||
- name
|
||||
- sharable (boolean)
|
||||
- created_at
|
||||
|
||||
#### Item Model
|
||||
|
||||
- id
|
||||
- list_id
|
||||
- category
|
||||
- quantity (double)
|
||||
- name
|
||||
- created_at
|
||||
- deleted_at
|
||||
|
||||
## Architecture
|
||||
|
||||
Pure PHP with no dependencies:
|
||||
|
||||
- **Database**: SQLite with PDO
|
||||
- **Router**: Custom lightweight router
|
||||
- **Structure**: Simple MVC pattern
|
||||
- **CORS**: Enabled for mobile/web apps
|
||||
|
||||
## WebSocket Server
|
||||
|
||||
WebSocket support will be implemented separately for real-time collaboration features.
|
||||
See [LICENSE](./LICENSE) file for details.
|
||||
|
||||
Reference in New Issue
Block a user