Beachcasts/doctrine-expressive-example

Example PHP REST API application built with Expressive using Doctrine ORM, complete with associations, pagination, and DB connectivity inside Docker containers. Used in #Beachcasts videos on YouTube.

doctrine-expressive-example

Example PHP REST API application spread across 2 Docker containers. (1=Apache, 2=MySQL) I used Zend Expressive with Doctrine ORM in an effort to help document usage of both in a typical scenario. The application leveraged the zend-expressive-skeleton as a starting point, and was installed set up for Modules using FastRoute, zend-servicemanager, and no template engine (since it is a REST API responding with Json).

The Doctrine Entities also include example usage of Associations between Entities (see the OneToMany association in Bank using ArrayCollection to ManyToOne association in Branch) as well as parent-child relationships within the same Entity (See the Bank associations - ManyToOne $parent and OneToMany $children using ArrayCollection).

Knowledge shared through example

• Zend Expressive usage
  • JsonResponse usage
  • Middleware usage
  • FastRoute usage
  • UrlHelper usage for hypermedia link creation
• container-interop-doctrine usage
• ramsey/uuid and ramsey/uuid-doctrine usages for primary keys in Announcements module, where routes also had to accommodate the UUID pattern of URLs - see the RoutesDelegator.php.
• Doctrine ORM usage
  • OneToMany Bidirectional and self-referencing association example (See Bank and Branch Entities)
  • ManyToOne unidirectional association example (See Bank and Branch Entities)
  • ArrayCollection example (See Bank and Branch Entities)
  • EntityManager examples
  • RepositoryManager examples
  • Pagination usage (see Read Handlers)
  • Associations represented in data output (see View Handlers)
  • CLI config
• PHP v7.2 feature usage

Installation

• Step 1 - Clone this repo to desired location
• Step 2 - Change directory to newly cloned repo via CLI cd /new/cloned/location
• Step 3 - Run docker-compose docker-compose up -d
• Step 4 - copy/rename the following config files
  • /config/autoload/development.local.php.dist >>> development.local.php
  • /config/autoload/doctrine.local.php.dist >>> doctrine.local.php
  • /config/autoload/local.php.dist >>> local.php
  • /config/development.config.php.dist >>> development.config.php
• Step 5 (optional) - Use docker-compose to clean up the example application docker-compose down

Usage

At this point the REST API should work. (The following REST endpoints return a listing from the DB.)

• http://localhost:8080/announcements
• http://localhost:8080/banks
• http://localhost:8080/branches

Each of these can be called as an HTTP GET, or an HTTP POST with Json fields payload. (See example body content in docblocks of Create and Update Handlers. Sample Json data for requests can be found in /data.)

In addition to these endpoints the hypermedia in each response provides information to additional endpoints.

CLI Tools

Also, the Zend Expressive, Doctrine DBAL, and Doctrine CLI commands are available by gaining the terminal from Docker.

• docker ps will provide the container ids to use in the following command.
• docker exec -i -t {container-id} bash

Replace {container-id} with the Docker container ID from the docker ps for the web container.

Then from the root prompt the CLI tools are available. Example commands are:

• php vendor/bin/doctrine list
• php vendor/bin/doctrine-dbal list
• php vendor/bin/expressive
• or php vendor/doctrine/bin/doctrine list

Constructive advice welcome

This code is an example, but any advice to help make this a more awesome teaching tool is welcome. Please submit a ticket with details, or better yet, submit a pull request. Thank you.

Behavioral API testing

coming soon