contributte/apitte-skeleton

🎁 API / REST API / JSON API / PSR-7 / Middlewares project skeleton based on Nette Framework (@nette), Apitte (@apitte), Doctrine (@nettrine) and Contributte (@contributte) libraries by @f3l1x.

Website 🚀 contributte.org | Contact 👨🏻‍💻 f3l1x.io | Twitter 🐦 @contributte

---

Goal

Main goal is to provide best prepared API starter-kit project for Nette-Apitte developers.

Focused on:

• 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

You can try it out yourself either by running it with docker, or more easily with docker-compose.

Demo

https://examples.contributte.org/apitte-skeleton/

Install with docker

1. At first, use composer to install this project.

   composer create-project -s dev contributte/apitte-skeleton

2. After that, you have to setup database.

   1. Setup PostgreSQL 10. You can start it manually or use docker image dockette/postgres:15.

      docker run -it -p 5432:5432 -e POSTGRES_PASSWORD=contributte -e POSTGRES_USER=contributte dockette/postgres:15

      Or use make task, make docker-postgres.

   2. Setup MariaDB 10.4. You can start it manually or use docker image mariadb:10.4.

      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

      Or use make task, make docker-mariadb.

3. Custom configuration file is located at config/local.neon. Edit it if you want.

   Default configuration should look like this. Pick PostgreSQL or MariaDB.

   # Host Config
   parameters:
   
       # 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

4. Ok database is now running and application is configured to connect to it. Let's create initial data.

   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 via task make build.

5. Start your devstack or use PHP local development server.

   You can start PHP server by running php -S localhost:8000 -t www or use prepared make task make dev.

6. 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 protected]&_access_token=admin
   • [GET] http://localhost:8000/api/v1/static/text
   • [POST] http://localhost:8000/api/v1/users/create

Install with docker compose

1. At first, use composer to install this project.

   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.

   # Host Config
   parameters:
   
       # 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 protected]&_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 + themes
• ReDoc
• other

Features

Here is a list of all features you can find in this project.

• PHP 8.2+
• 📦 Packages
  • Nette 3+
  • Contributte
• 🌳 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
• ❗ Tracy
  • Cool error 500 page

Composer packages

Take a detailed look 👀 at each single package.

• contributte/bootstrap
• contributte/di
• contributte/http
• contributte/security
• contributte/utils
• contributte/tracy
• contributte/console
• contributte/neonizer
• contributte/monolog
• contributte/apitte

Doctrine

• contributte/doctrine-orm
• contributte/doctrine-dbal
• contributte/doctrine-migrations
• contributte/doctrine-fixtures

Nette

• nette/finder
• nette/robot-loader

Symfony

• symfony/serializer
• symfony/validator

Demo

Development

See how to contribute to this package.

This package is currently maintaining by these authors.

---

Consider to support contributte development team. Also thank you for using this project.

apitte-skeleton's Issues

config.neon does not allow App\Controllers\Xyx... set up

I need to send some params from config.neon to controller. So I tried to write

parameters:
	crm:
		token: 'qeryuteykljkmjdhgvfarerhhhilhiohiohfrtxgzx'

services:
	- App\Controllers\CampaignsController(%crm.token%)

But this throws me an erro which says: Multiple services of type App\Controllers\CampaignsController found: 01, resource.App_Controllers.3.

I dont see any other controller with the same name. It seems Apitte does not allowe to configurate controllers via

public function __contruct($crm_token) {}

How can I do it if it is possible?

TypeError at App\Model\Database\Entity\User::getLastLoggedAt()

TypeError

App\Model\Database\Entity\User::getLastLoggedAt(): Return value must be of type ?App\Model\Utils\DateTime, DateTime returned

Exactly the same works at https://github.com/contributte/webapp-skeleton/blob/master/app/model/Database/Entity/User.php

I am missing what is different.

How to reproduce:

• Set lastLoggedAt to a random user.

Workaround is to set dates to build-in \DateTime type.

Invalid OpenAPI definition

Generated OpenAPI definition is invalid.

Ways to validate:

• Call API at validator.swagger.io
• Copy&paste to editor.swagger.io

JsonDispatcher misuses @Tag annotation

I believe that Apitte\Core\Annotation\Controller\Tag annotation was created for documentation purpose (or at least it is used for OpenAPI definition generation). Therefore, all request bodies cannot have the same name "request.dto".

App\Model\Api\Dispatcher\JsonDispatcher

		// Get incoming request entity class, if defined. Otherwise, skip transforming.
		if (!($entity = $endpoint->getTag('request.dto'))) {
			return $request;
		}

How to inject request and response to __construct

I am not sure but it seems it is not possible to inject request and response to the constructor of the BaseController. Is it possible or not? I want to achieve something like this

namespace App\Controllers;

use Apitte\Core\Http\ApiRequest;
use Apitte\Core\Http\ApiResponse;

/**
 * @GroupPath("/api")
 * @GroupId("api")
 */
abstract class BaseController implements IController
{

  /**
   * ApiRequest
   */
  public $request;

  /**
   * ApiResponse
   */
  public $response;

  public function __construct(ApiRequest $request, ApiResponse $response)
  {
    $this->request = $request;
    $this->response = $response;
  }

or this

namespace App\Controllers;

use Apitte\Core\Http\ApiRequest;
use Apitte\Core\Http\ApiResponse;

/**
 * @GroupPath("/api")
 * @GroupId("api")
 */
abstract class BaseController implements IController
{

  /**
   * @inject
   * @var ApiRequest
   */
  public $request;

  /**
   * @inject
   * @var ApiResponse
   */
  public $response;

Error logging not working

Same behavior as described on https://forum.nette.org/cs/33974-apitte-skeleton-nelogguje-errory-a-jen-zobrazi-error-500 or https://forum.nette.org/cs/34583-apitte-debugovani-a-logovani - info + debug works but error/exception not. So there is no possiblity to debug anything when exception raises during API calls.

Symfony AnnotationLoader missing

AnnotationLoader has been deprecated for a while in < 7. It has been replaced by AttributeLoader since then.

Please, change symfony.serializer.annotationLoader in services.neon from Symfony\Component\Serializer\Mapping\Loader\AnnotationLoader to Symfony\Component\Serializer\Mapping\Loader\AttributeLoader.

Service of type Contributte\Middlewares\Application\IApplication not found.

Hi, I installed apitte-skeleton on apache without docker and now when I run application I get this exception.

Internal Server Error
On Tracy: \MissingServiceException: Service of type Contributte\Middlewares\Application\IApplication not found.

Before I have also problem with
Error: Call to undefined method Symfony\Component\Validator\ValidatorBuilder::enableAnnotationMapping()
but thats now somehow ok.

I feel like my computer trolls me. Does anyone know what to do? Thanks.

Deserialization in requests is not working

Hi,
I have trouble deserializing a datetime object from request body.

I added birthDate field to CreateUserReqDto. Should I deserialize it manually?

In a documentation I found that DTOs should inherit Apitte\Core\Mapping\Request\BasicEntity and presumably override normalize method (which is not mentioned in the documentation). But it doesn't work.

I guess the same problem is going to be with other non-primitive types.