Download the PHP package huge/rest without Composer

HugeRest

Framework PHP pour créer simplement, rapidement et efficacement une webapp REST Exemple : https://github.com/ffremont/HugeRest-samples

Installation

Installer avec composer

.htaccess :

Fonctionnalités

• Définition des ressources et des chemins via : @Resource / @Path("CHEMIN")
• Gestion des méthodes HTTP : @Get, @Put, @Post, @Delete
• Personnalisation des types mimes : @Consumes({"...", "..."})
  • Permet de définir les accepts (GET, Delete) ou le content-type (POST, PUT)
• Personnalisation du content type de la réponse : @Produces({"...", "..."})
• Personnalisation des contenus
  • interprétation du contenu de la requête : implémentation de Huge\Rest\Process\IBodyReader
  • interprétation du contenu de la réponse : implémentation de Huge\Rest\Process\IBodyWriter
  • validation des contenus l'interface : Huge\Rest\Data\IValidator
• Gestion des erreurs extra-souple : implémentation de Huge\Rest\Process\IExceptionMapper
• Gestion de filtres sur les requêtes : implémentation de Huge\Rest\Process\IFilter
• Gestion d'intercepteurs sur les requêtes : implémentation de Huge\Rest\Process\IInterceptor
• Cache : basé sur doctrine cache
• Annotations basé sur doctrine annotations

Configuration

Création d'une ressource

• Une ressource REST se matérialise par une classe PHP annotée. C'est un composant au sens Huge\IoC.

• Utilisation des annotations :

  • @Resource obligatoire
  • @Path facultatif
  • @Consumes facultatif
    • Si POST, PUT cela correspond au contentType de la requête
    • Sinon, cela correspond à l'entête accept de la requête
  • @Produces facultatif
    • Définition du typeMime de sortie
    • Si POST, PUT cela correspond à l'entête accept de la requête
    • Sinon, cela correspond au contentType de la réponse
• Les @Path sont des regexp
  • les chaînes trouvées sont ajoutées en paramètres de la fonction
• Liste des tokens :
  • ':mString' => '([a-zA-Z]+)'
  • ':mNumber' => '([0-9]+)'
  • ':mAlpha' => '([a-zA-Z0-9-_]+)'
  • ':oString' => '([a-zA-Z]*)'
  • ':oNumber' => '([0-9]*)'
  • ':oAlpha' => '([a-zA-Z0-9-_]*)'

Gérer un contenu de requête

• Pour gérer les types mime des requêtes HTTP vous avez la possibilité d'implémenter vos propres "IBodyReader"

• Interface à implémenter : Huge\Rest\Process\IBodyReader

• Liste et configuration des readers disponibles (l'instance HttpResquet = $r)
  • 'application/x-www-form-urlencoded' => 'Huge\Rest\Process\Readers\FormReader', => $r->getBody() : $_REQUEST
  • 'application/json' => 'Huge\Rest\Process\Readers\JsonReader', => $r->getBody() : json_decode
  • 'text/plain' => 'Huge\Rest\Process\Readers\TextReader', => $r-getBody() => au body de la request
  • 'multipart/form-data' => 'Huge\Rest\Process\Readers\UploadReader', => $r->getBody() : instance Huge\Rest\Http\HttpFiles
  • 'multipart/octet-stream' => 'Huge\Rest\Process\Readers\UploadReader', // idem
  • 'application/octet-stream' => 'Huge\Rest\Process\Readers\BinaryReader' => $r->getBody() : instance Huge\Rest\Data\TempFile

Gérer un contenu de réponse

• Une fonction d'une ressource retourne une instance de l'objet Huge\Rest\Http\HttpResponse. Cette dernière peut avoir l'attribut "entity" de valorisé qui sera à convertir en fonction du contentType souhaité de la réponse HTTP.

• Interface à implémenter : Huge\Rest\Process\IBodyWriter

• Liste et configurations des writers disponibles
  • 'application/x-www-form-urlencoded' => 'Huge\Rest\Process\Writers\FormWriter', => encode $entity avec urlencode
  • 'application/json' => 'Huge\Rest\Process\Writers\JsonWriter', => encode $entity avec json_encode
  • 'text/plain' => 'Huge\Rest\Process\Writers\TextWriter' => caste en string

Filtrer les requêtes et réponses

• Les filtres permettent d'exercer des contrôles avant les traitements REST. Un filtre est un composant au sens Huge\IoC.
• Interface à implémenter : Huge\Rest\Process\IRequestFilter
• Interface à implémenter : Huge\Rest\Process\IResponseFilter

Intercepter les traitements REST

• Pour différentes raisons vous aurez besoin de connaître le début et la fin des traitements de votre API. Un intercepteur est un composant au sens Huge\IoC.
• Interface à implémenter : Huge\Rest\Process\IInterceptor

Validateurs sur les modèles

• Basé sur fuelphp validation https://github.com/fuelphp/validation
• Il est possible de valider les données qui sont passées dans le body de la requête.

• Interface que le modèle doit implémenter : Huge\Rest\Data\IValidator

  • Lancement de l'exception : Huge\Rest\Exceptions\ValidationException
• Personnalisation du validateur fuelPhp \Huge\Rest\Data\IFuelValidatorFactory

Personnaliser les erreurs

• Votre webapp va pouvoir emettre des exceptions qu'il va falloir convertir en réponse HTTP. Pour réaliser cela, il va être nécessaire d'enregistrer des couples selon le format : "Nom de l'exception" => "Nom de la classe qui implémente".
• Interface à implémenter : Huge\Rest\Process\IExceptionMapper

• Il est possible de définir un mapper d'exceptions par défaut "Exception" => "MonMapper"

• Liste des mappers :
  • 'Huge\Rest\Exceptions\NotFoundResourceException' => 'Huge\Rest\Exceptions\Mappers\NotFoundResourceExceptionMapper',
  • 'Huge\Rest\Exceptions\InvalidResponseException' => 'Huge\Rest\Exceptions\Mappers\InvalidResponseExceptionMapper',
  • 'Huge\Rest\Exceptions\ValidationException' => 'Huge\Rest\Exceptions\Mappers\ValidationExceptionMapper',
  • 'Huge\Rest\Exceptions\WebApplicationException' => 'Huge\Rest\Exceptions\Mappers\WebApplicationExceptionMapper',
  • 'Huge\Rest\Exceptions\SizeLimitExceededException' => 'Huge\Rest\Exceptions\Mappers\SizeLimitExceededExceptionMapper',
  • 'Exception' => 'Huge\Rest\Exceptions\Mappers\DefaultExceptionMapper'

Logger

• Implémenter la factory : Huge\IoC\Factory\ILogFactory
• Ajouter le composant dans votre conteneur de plus haut niveau
  • Dans le cas où vous avez conteneurs et que chacun dispose de son implémentation. L'injection (@Autowired de ILogFactory) ne marchera pas car implémentations seront détectées.
  • Généralement, le conteneur WebApp contient l'implémentation et les classes des tests
• Logger factory (composant) vide : Huge\Rest\Log\NullLoggerFactory

Ordonnancement

• Analyse de la requête HTTP
  • à partir du composant Huge\Rest\Http\HttpRequest
  • détermination d'une route : Huge\Rest\Routing\Route (composant)
  • si aucune route n'existe, lancement de Huge\Rest\Exceptions\NotFoundResourceException
• Analyse du contenu de la requête (POST ou PUT)
  • utilisation des IBodyReader
• Exécution des Huge\Rest\Process\IRequestFilter
• Exécution de la fonction start des intercepteurs Huge\Rest\Process\IInterceptor
• EXECUTION DU TRAITEMENT LIE A LA RESSOURCE
• Détermination du contentType à appliquer dans la réponse HTTP
  • utilisation des IBodyWriter
• Exécution des Huge\Rest\Process\IResponseFilter
• Exécution de la fonction end des intercepteurs Huge\Rest\Process\IInterceptor
• Construction de la réponse : Huge\Rest\Http\HttpResponse (fonction build)

Limitations

• La gestion des erreurs ne permet pas d'exploiter l'héritage des exceptions
• Logger basé sur l'interface Psr\Log : https://packagist.org/packages/psr/log
• Basé sur Huge\IoC
• Validateur basé sur fuel validation

Tests

• Tests unitaires : phpunit -c src/test/resources/phpunit.xml --testsuite TU
• Tests d'intégration avec apache2 sur src/test/webapp : phpunit -c src/test/resources/phpunit.xml --testsuite IT