diff --git a/README.md b/README.md index 7ba070a..bb610e8 100644 --- a/README.md +++ b/README.md @@ -24,246 +24,433 @@ Website ๐Ÿš€ contributte.org | Contact ----- -## Goal +## What is Apitte Skeleton? -Main goal is to provide best prepared API starter-kit project for Nette-Apitte developers. +**Apitte Skeleton** is a fully-featured, production-ready starter template for building modern REST APIs with PHP. It combines the best packages from the Nette and Contributte ecosystems to give you a solid foundation for your API project. -Focused on: +Perfect for developers who want to: +- ๐Ÿš€ Start building APIs quickly without boilerplate setup +- ๐Ÿ“š Learn best practices for PHP API development +- ๐Ÿ—๏ธ Build production-ready REST/JSON APIs with proper architecture +- ๐Ÿ”’ Implement authentication, validation, and database management out of the box -- PHP 8.2+ -- `nette/*` packages -- build PSR-7 API via `contributte/apitte` -- Doctrine ORM via `nettrine/*` -- Symfony components via `contributte/*` -- codestyle checking via **CodeSniffer** and `contributte/qa` -- static analysing via **phpstan** and `contributte/phpstan` -- unit / integration tests via **Nette Tester** and `contributte/tester` +### What's Inside? -You can try it out yourself either by running it with docker, or more easily with docker-compose. +- **Modern PHP 8.2+** with strict types and best practices +- **RESTful API** built with [Apitte](https://contributte.org/packages/contributte/apitte.html) (PSR-7 compliant) +- **Database ORM** with [Doctrine](https://www.doctrine-project.org/) and migrations support +- **OpenAPI/Swagger** documentation auto-generation +- **Authentication** with token-based security +- **Input Validation** using Symfony Validator +- **Code Quality Tools** (PHPStan, CodeSniffer) +- **Testing Suite** with Nette Tester +- **Docker Support** for easy deployment +- **Example Endpoints** to learn from -## Demo +### Live Demo -https://examples.contributte.org/apitte-skeleton/ +Try it out: https://examples.contributte.org/apitte-skeleton/ -## Install with [docker](https://github.com/docker/docker/) +## Prerequisites -1) At first, use composer to install this project. +Before you begin, make sure you have: - ```bash - composer create-project -s dev contributte/apitte-skeleton - ``` +- **PHP 8.2 or higher** installed +- **Composer** (PHP package manager) +- **Docker & Docker Compose** (recommended) OR +- **PostgreSQL 13+** or **MariaDB 10.4+** (if not using Docker) +- Basic knowledge of PHP and REST APIs -2) After that, you have to setup database. +## ๐Ÿš€ Quick Start (Recommended) - 1. Setup PostgreSQL 10. You can start it manually or use docker image `dockette/postgres:15`. +The easiest way to get started is using **Docker Compose**, which sets up everything automatically. - ```bash - docker run -it -p 5432:5432 -e POSTGRES_PASSWORD=contributte -e POSTGRES_USER=contributte dockette/postgres:15 - ``` +### Option 1: Docker Compose (Easiest - Recommended for Beginners) - Or use make task, `make docker-postgres`. +```bash +# 1. Create a new project +composer create-project -s dev contributte/apitte-skeleton my-api-project +cd my-api-project - 2. Setup MariaDB 10.4. You can start it manually or use docker image `mariadb:10.4`. +# 2. Start the application (this will download Docker images, install dependencies, and set up the database) +docker-compose up +``` - ```bash - docker run -it -d -p 3306:3306 -e MARIADB_ROOT_PASSWORD=contributte -e MARIADB_PASSWORD=contributte -e MARIADB_USER=contributte -e MARIADB_DATABASE=contributte mariadb:10.4 - ``` +That's it! ๐ŸŽ‰ The API is now running at **http://localhost:8000** - Or use make task, `make docker-mariadb`. +> **Note**: The first run takes a few minutes to download Docker images and set up everything. Subsequent starts are much faster. -3) Custom configuration file is located at `config/local.neon`. Edit it if you want. +### Option 2: Manual Setup with Docker Database - Default configuration should look like this. Pick PostgreSQL or MariaDB. +If you prefer more control or want to run PHP locally: - ```neon - # Host Config - parameters: +```bash +# 1. Create a new project +composer create-project -s dev contributte/apitte-skeleton my-api-project +cd my-api-project - # Database - database: +# 2. Install dependencies +composer install - # Postgres - driver: pdo_pgsql - host: database - dbname: contributte - user: contributte - password: contributte - port: 5432 +# 3. Create local configuration +cp config/local.neon.example config/local.neon - # MariaDB - driver: pdo_mysql - host: database - dbname: contributte - user: contributte - password: contributte - port: 3306 - ``` +# 4. Start a database (choose PostgreSQL OR MariaDB) -4) Ok database is now running and application is configured to connect to it. Let's create initial data. +# PostgreSQL (recommended): +make docker-postgres - Run `NETTE_DEBUG=1 bin/console migrations:migrate` to create tables. - Run `NETTE_DEBUG=1 bin/console doctrine:fixtures:load --append` to create first user(s). +# OR MariaDB: +make docker-mariadb - Or via task `make build`. +# 5. Set up the database schema and load sample data +make build -5) Start your devstack or use PHP local development server. +# 6. Start the PHP development server +make dev +``` - You can start PHP server by running `php -S localhost:8000 -t www` or use prepared make task `make dev`. +Your API is now running at **http://localhost:8000** -6) Open http://localhost and enjoy! +### Option 3: Full Manual Setup (Advanced) - Take a look at: - - [GET] http://localhost:8000/api/public/v1/openapi/meta (Swagger format) - - [GET] http://localhost:8000/api/v1/users - - [GET] http://localhost:8000/api/v1/users?_access_token=admin - - [GET] http://localhost:8000/api/v1/users/1?_access_token=admin - - [GET] http://localhost:8000/api/v1/users/999?_access_token=admin - - [GET] http://localhost:8000/api/v1/users/email?email=admin@admin.cz&_access_token=admin - - [GET] http://localhost:8000/api/v1/static/text - - [POST] http://localhost:8000/api/v1/users/create +If you have your own database server: -## Install with [docker compose](https://github.com/docker/compose) +```bash +# 1. Create the project +composer create-project -s dev contributte/apitte-skeleton my-api-project +cd my-api-project -1) At first, use composer to install this project. +# 2. Install dependencies +composer install - ``` - composer create-project -s dev contributte/apitte-skeleton - ``` - -2) Modify `config/local.neon` and set host to `postgres` or `mariadb` - - Default configuration should look like this. There is preconfigured database. Pick PostgreSQL or MariaDB. - - ```neon - # Host Config - parameters: +# 3. Configure your database connection +# Edit config/local.neon with your database credentials +cp config/local.neon.example config/local.neon +nano config/local.neon # or use your favorite editor - # Database - database: - - # Postgres - driver: pdo_pgsql - host: database - dbname: contributte - user: contributte - password: contributte - port: 5432 - - # MariaDB - driver: pdo_mysql - host: database - dbname: contributte - user: contributte - password: contributte - port: 3306 - ``` - -3) Run `docker-compose up` - -4) Open http://localhost and enjoy! - - Take a look at: - - [GET] http://localhost:8000/api/public/v1/openapi/meta (Swagger format) - - [GET] http://localhost:8000/api/v1/users - - [GET] http://localhost:8000/api/v1/users?_access_token=admin - - [GET] http://localhost:8000/api/v1/users/1?_access_token=admin - - [GET] http://localhost:8000/api/v1/users/999?_access_token=admin - - [GET] http://localhost:8000/api/v1/users/email?email=admin@admin.cz&_access_token=admin - - [POST] http://localhost:8000/api/v1/users/create - - [GET] http://localhost:8000/api/v1/static/text?_access_token=admin - - [GET] http://localhost:8000/api/v1/error/exception?_access_token=admin - -## (Optional) REST API documentation - -Since we have OpenAPI specification available at `/api/public/v1/openapi/meta` you just need to add UI for it (e.g. to `www/doc` directory or as a standalone application). - -Available options are: - -- [Swagger UI](https://swagger.io/tools/swagger-ui/) + [themes](https://github.com/ostranme/swagger-ui-themes) -- [ReDoc](https://github.com/Redocly/redoc) -- other - -## Features - -Here is a list of all features you can find in this project. - -- PHP 8.2+ -- :package: Packages - - Nette 3+ - - Contributte -- :deciduous_tree: Structure - - `app` - - `config` - configuration files - - `env` - prod/dev/test environments - - `app` - application configs - - `ext` - extensions configs - - `local.neon` - local runtime config - - `local.neon.dist` - template for local config - - `domain` - business logic and domain specific classes - - `model` - application backbone - - `module` - API module - - `resources` - static content for mails and others - - `bootstrap.php` - Nette entrypoint - - `bin` - console entrypoint (`bin/console`) - - `db` - database files - - `fixtures` - PHP fixtures - - `migrations` - migrations files - - `docs` - documentation - - `vae` - - `log` - runtime and error logs - - `tmp` - temp files and cache - - `tests` - test engine and many cases - - `tests/cases/E2E` - PhpStorm's requests files (`api.http`) - - `tests/cases/Integration` - - `tests/cases/Unit` - - `vendor` - composer's folder - - `www` - public content -- :exclamation: Tracy - - Cool error 500 page - -### Composer packages - -Take a detailed look :eyes: at each single package. - -- [contributte/bootstrap](https://contributte.org/packages/contributte/bootstrap.html) -- [contributte/di](https://contributte.org/packages/contributte/di.html) -- [contributte/http](https://contributte.org/packages/contributte/http.html) -- [contributte/security](https://contributte.org/packages/contributte/security.html) -- [contributte/utils](https://contributte.org/packages/contributte/utils.html) -- [contributte/tracy](https://contributte.org/packages/contributte/tracy.html) -- [contributte/console](https://contributte.org/packages/contributte/console.html) -- [contributte/neonizer](https://contributte.org/packages/contributte/neonizer.html) -- [contributte/monolog](https://contributte.org/packages/contributte/monolog.html) -- [contributte/apitte](https://contributte.org/packages/contributte/apitte.html) - -**Doctrine** - -- [contributte/doctrine-orm](https://contributte.org/packages/contributte/doctrine-orm.html) -- [contributte/doctrine-dbal](https://contributte.org/packages/contributte/doctrine-dbal.html) -- [contributte/doctrine-migrations](https://contributte.org/packages/contributte/doctrine-migrations.html) -- [contributte/doctrine-fixtures](https://contributte.org/packages/contributte/doctrine-fixtures.html) - -**Nette** - -- [nette/finder](https://github.com/nette/finder) -- [nette/robot-loader](https://github.com/nette/robot-loader) - -**Symfony** - -- [symfony/serializer](https://github.com/symfony/serializer) -- [symfony/validator](https://github.com/symfony/validator) - -## Demo +# 4. Set up database +NETTE_DEBUG=1 bin/console migrations:migrate --no-interaction +NETTE_DEBUG=1 bin/console doctrine:fixtures:load --no-interaction + +# 5. Start PHP server +php -S localhost:8000 -t www +``` + +## ๐Ÿงช Try Out the API + +Once your server is running, try these example endpoints: + +### Public Endpoints (No Authentication) +- **API Documentation**: http://localhost:8000/api/public/v1/openapi/meta + OpenAPI/Swagger specification for all endpoints + +### Protected Endpoints (Use `?_access_token=admin`) + +The skeleton comes with a demo user. Use `_access_token=admin` to authenticate: + +- **List all users** + http://localhost:8000/api/v1/users?_access_token=admin + +- **Get specific user** + http://localhost:8000/api/v1/users/1?_access_token=admin + +- **Find user by email** + http://localhost:8000/api/v1/users/email?email=admin@admin.cz&_access_token=admin + +- **Static text example** + http://localhost:8000/api/v1/static/text?_access_token=admin + +### Testing Different Responses + +- **User not found (404)** + http://localhost:8000/api/v1/users/999?_access_token=admin + +- **Error handling example** + http://localhost:8000/api/v1/error/exception?_access_token=admin + +### Create a New User (POST) + +```bash +curl -X POST http://localhost:8000/api/v1/users/create \ + -H "Content-Type: application/json" \ + -d '{"name":"John Doe","email":"john@example.com"}' +``` + +## ๐Ÿ“– API Documentation UI + +The skeleton provides OpenAPI specification, but you can add a visual UI for better documentation: + +**OpenAPI Spec**: http://localhost:8000/api/public/v1/openapi/meta + +### Add Swagger UI (Optional) + +1. Download [Swagger UI](https://github.com/swagger-api/swagger-ui/releases) +2. Extract to `www/docs/` +3. Point it to `/api/public/v1/openapi/meta` +4. Access at http://localhost:8000/docs/ + +**Alternatives**: [ReDoc](https://github.com/Redocly/redoc), [Swagger UI Themes](https://github.com/ostranme/swagger-ui-themes) + +## ๐Ÿ› ๏ธ Available Commands + +The project includes helpful `make` commands: + +### Development +```bash +make dev # Start PHP development server +make build # Rebuild database schema and load fixtures +make clean # Clear cache and logs +``` + +### Code Quality +```bash +make qa # Run all quality checks (cs + phpstan) +make cs # Check code style +make csf # Fix code style issues +make phpstan # Run static analysis +make tests # Run test suite +make coverage # Generate test coverage report +``` + +### Database Tools +```bash +make docker-postgres # Start PostgreSQL in Docker +make docker-mariadb # Start MariaDB in Docker +make docker-adminer # Start Adminer (DB management UI) +``` + +Access Adminer at http://localhost:8080 when using Docker Compose. + +## ๐Ÿ“ Project Structure + +Understanding the folder structure helps you navigate the codebase: + +``` +apitte-skeleton/ +โ”œโ”€โ”€ app/ # Application code +โ”‚ โ”œโ”€โ”€ Domain/ # Business logic and entities +โ”‚ โ”‚ โ””โ”€โ”€ User/ # User domain (entity, repository, etc.) +โ”‚ โ”œโ”€โ”€ Model/ # Application services and backbone +โ”‚ โ”œโ”€โ”€ Module/ # API controllers +โ”‚ โ”‚ โ”œโ”€โ”€ PubV1/ # Public API v1 (no auth required) +โ”‚ โ”‚ โ””โ”€โ”€ V1/ # Protected API v1 (auth required) +โ”‚ โ””โ”€โ”€ Bootstrap.php # Application bootstrap +โ”‚ +โ”œโ”€โ”€ config/ # Configuration files +โ”‚ โ”œโ”€โ”€ env/ # Environment-specific configs (dev/prod/test) +โ”‚ โ”œโ”€โ”€ local.neon # Your local config (git-ignored) +โ”‚ โ””โ”€โ”€ local.neon.example # Template for local config +โ”‚ +โ”œโ”€โ”€ db/ # Database files +โ”‚ โ”œโ”€โ”€ fixtures/ # Sample data (PHP fixtures) +โ”‚ โ””โ”€โ”€ migrations/ # Database migrations +โ”‚ +โ”œโ”€โ”€ tests/ # Test suite +โ”‚ โ”œโ”€โ”€ cases/E2E/ # End-to-end tests (API requests) +โ”‚ โ”œโ”€โ”€ cases/Integration/ # Integration tests +โ”‚ โ””โ”€โ”€ cases/Unit/ # Unit tests +โ”‚ +โ”œโ”€โ”€ var/ # Runtime files +โ”‚ โ”œโ”€โ”€ log/ # Application logs +โ”‚ โ””โ”€โ”€ tmp/ # Cache and temporary files +โ”‚ +โ”œโ”€โ”€ www/ # Public web root +โ”‚ โ””โ”€โ”€ index.php # Entry point +โ”‚ +โ”œโ”€โ”€ bin/ # Executable scripts +โ”‚ โ””โ”€โ”€ console # CLI console for commands +โ”‚ +โ””โ”€โ”€ docker-compose.yml # Docker Compose configuration +``` + +### Key Files + +- **app/Module/V1/UsersController.php** - Example API controller +- **app/Domain/User/User.php** - Example entity +- **config/ext/apitte.neon** - API routing configuration +- **db/fixtures/UserFixture.php** - Sample user data + +## ๐ŸŽฏ Next Steps + +Now that you have the API running, here's what you can do: + +1. **Explore the Code** + - Check out `app/Module/V1/UsersController.php` to see how endpoints are built + - Look at `app/Domain/User/User.php` to understand the entity structure + - Review `config/ext/apitte.neon` for API configuration + +2. **Create Your First Endpoint** + - Add a new controller in `app/Module/V1/` + - Define routes using Apitte annotations + - Register it in the DI container + +3. **Customize the Database** + - Modify entities in `app/Domain/` + - Create migrations: `bin/console migrations:diff` + - Apply migrations: `bin/console migrations:migrate` + +4. **Add Your Business Logic** + - Create new domains in `app/Domain/` + - Add services in `app/Model/` + - Write tests in `tests/` + +5. **Learn from Examples** + - Study the included User CRUD endpoints + - Check the authentication middleware + - Review validation rules + +## ๐Ÿ“š Documentation & Resources + +- **Apitte Documentation**: https://contributte.org/packages/contributte/apitte.html +- **Nette Framework**: https://nette.org/ +- **Doctrine ORM**: https://www.doctrine-project.org/ +- **All Contributte Packages**: https://contributte.org/ + +## ๐Ÿ› Troubleshooting + +### Port Already in Use +```bash +# If port 8000 is busy, use a different port: +php -S localhost:3000 -t www +``` + +### Database Connection Issues +- Verify your database is running: `docker ps` +- Check `config/local.neon` has correct credentials +- For Docker Compose, use `host: postgres` or `host: mariadb` +- For local databases, use `host: 127.0.0.1` + +### Permission Errors +```bash +# Fix permissions for var/ directories: +chmod -R 0777 var/tmp var/log +``` + +### Composer Issues +```bash +# Clear Composer cache and reinstall: +composer clear-cache +rm -rf vendor/ +composer install +``` + +### Database Not Created +```bash +# Rebuild database from scratch: +make build +``` + +### Cache Issues +```bash +# Clear application cache: +make clean +``` + +## ๐Ÿ”’ Security Notes + +- The default admin token (`admin`) is for **development only** +- Change authentication mechanism for production +- Never commit `config/local.neon` (it's git-ignored by default) +- Review security settings before deploying + +## ๐Ÿค Contributing + +Want to contribute? Great! Check out: +- [Contributing Guide](https://contributte.org/contributing.html) +- Report issues on [GitHub](https://github.com/contributte/apitte-skeleton/issues) +- Join the community on [Gitter](https://bit.ly/ctteg) + +## ๐Ÿ“ Technical Details + +### Technology Stack + +Here is a list of all features and technologies included in this project: + +- **PHP 8.2+** with modern features +- :package: **Core Packages** + - Nette 3+ Framework + - Contributte Ecosystem +- :deciduous_tree: **Project Structure** + - `app/` + - `Domain/` - business logic and domain entities + - `Model/` - application services + - `Module/` - API controllers (PubV1, V1) + - `Bootstrap.php` - application entrypoint + - `config/` - configuration files + - `env/` - environment configs (prod/dev/test) + - `local.neon` - local configuration + - `bin/console` - CLI console + - `db/` - database files + - `fixtures/` - sample data + - `migrations/` - database migrations + - `var/` + - `log/` - application logs + - `tmp/` - cache and temp files + - `tests/` - test suite + - `cases/E2E/` - end-to-end API tests + - `cases/Integration/` - integration tests + - `cases/Unit/` - unit tests + - `www/` - public webroot +- :exclamation: **Error Handling** + - Tracy debugger with beautiful error pages + +### Included Composer Packages + +Take a detailed look :eyes: at each package: + +**Core Contributte Packages** +- [contributte/bootstrap](https://contributte.org/packages/contributte/bootstrap.html) - Enhanced Nette bootstrapping +- [contributte/di](https://contributte.org/packages/contributte/di.html) - Dependency injection extensions +- [contributte/http](https://contributte.org/packages/contributte/http.html) - HTTP helpers and utilities +- [contributte/security](https://contributte.org/packages/contributte/security.html) - Security components +- [contributte/utils](https://contributte.org/packages/contributte/utils.html) - Common utilities +- [contributte/tracy](https://contributte.org/packages/contributte/tracy.html) - Enhanced Tracy debugger +- [contributte/console](https://contributte.org/packages/contributte/console.html) - Symfony Console integration +- [contributte/monolog](https://contributte.org/packages/contributte/monolog.html) - Monolog logging +- [contributte/apitte](https://contributte.org/packages/contributte/apitte.html) - **API framework** (the star of the show!) + +**Database (Nettrine/Doctrine)** +- [nettrine/orm](https://contributte.org/packages/nettrine/orm.html) - Doctrine ORM integration +- [nettrine/dbal](https://contributte.org/packages/nettrine/dbal.html) - Database abstraction layer +- [nettrine/migrations](https://contributte.org/packages/nettrine/migrations.html) - Database migrations +- [nettrine/fixtures](https://contributte.org/packages/nettrine/fixtures.html) - Test data fixtures + +**Symfony Components** +- [symfony/serializer](https://symfony.com/doc/current/components/serializer.html) - Object serialization +- [symfony/validator](https://symfony.com/doc/current/components/validator.html) - Input validation + +**Development Tools** +- [contributte/qa](https://contributte.org/packages/contributte/qa.html) - Code quality tools +- [contributte/phpstan](https://contributte.org/packages/contributte/phpstan.html) - Static analysis +- [nette/tester](https://tester.nette.org/) - Testing framework + +## ๐Ÿ“ธ Screenshots ![](.docs/assets/screenshot1.png) ![](.docs/assets/screenshot2.png) ![](.docs/assets/screenshot3.png) -## Development +## ๐Ÿ‘ฅ Development & Support + +### Getting Help + +- ๐Ÿ’ฌ **Gitter Chat**: [Join the conversation](https://bit.ly/ctteg) +- ๐Ÿ’ก **Forum**: [Ask questions](https://bit.ly/cttfo) +- ๐Ÿ› **Issues**: [Report bugs](https://github.com/contributte/apitte-skeleton/issues) +- ๐Ÿ“– **Documentation**: [contributte.org](https://contributte.org) + +### Contributing + +See [how to contribute](https://contributte.org/contributing.html) to this package. We welcome: +- Bug reports and fixes +- Documentation improvements +- Feature suggestions +- Code contributions -See [how to contribute](https://contributte.org/contributing.html) to this package. +### Maintainers -This package is currently maintaining by these authors. +This package is currently maintained by: