Bloatless Endocore

Endocore is a framework designed to quickly build web applications following the Action-Domain-Responder pattern.

Installation

The easiest and recommended way to start a new Endocore based application is to use the Endocore Sample App. This repository provides you with a boilerplate application including all necessary files and folders to start your project.

You can install the Endocore App using composer:

Documentation

Additionally to this documentation you should also have a look into the Endocore App sourcecode. It contains some well documented examples.

• Directory Structure
• Configuration
• Routing
  • GET Route
  • POST Route
  • Other route types
  • Route parameters
• Actions and Responder
  • Actions with JSON response
  • Actions with HTML response
• Domains
• Error Handling and Logging
  • Using the file logger
  • Logger configuration
  • Log Levels
  • Error responses
  • Throwing exceptions
  • Generic Exceptions
  • HTTP Exceptions

Directory Structure

Configuration

After installing the Endocore App you should check and adjust the config.php file the config folder. Most of the settings should be fine with their default values but if your application needs to use a MySQL database e.g. you need to add or adjust some values.

Routing

The routes of your application define which Action will be executed when a specified URL is requested. Each URL supported by your application needs to be routed to an action. You can adjust routes using the default.php file in the routes folder.

GET Route

This example routes the request path /about to the AboutAction in your applications Actions folder.

POST Route

This example handles a POST request to /customers and calls the AddCustomerAction in your application.

Other route types

Of course you can also define PUT, DELETE or any other valid request types in the same manner.

Route parameters

You can use placeholders within route patterns. These parameters will be passed to your action using the $arguments array.

This route would match URLs like e.g. /customers/123. The CustomerAction would receive an $arguments array like this:

You can additionally use a regular expression pattern to define which values the placeholder accepts.

This route for example would match /customers/123 but not customers/abc.

Segments wrapped in square brackets are considered optional like e.g.:

pattern' => '/customers[/{id:[0-9]+]'

Actions and Responder

Every request the application receives will be dispatched to an action as defined in your routes. The action handles this request. Typically by requesting data from a domain using input data from the request. The data from the domain is than passed to a responder which builds the HTTP response. This response is than returned back into the application by the action.

Endocore provides responders for HTML as well as JSON content. You can use this responders by extending the appropriate actions.

Actions with JSON response

This example shows how an Action inherits the JsonResponder from the JsonAction and is than able to respond json data using only methods provided by the framework.

Actions with HTML response

If you want to reply with HTML content you can inherit from the HtmlAction and make use auf the HtmlResponder.

This example will output a simple Hello World paragraph.

Domains

Domains handle the logic of your application. Domains can be a simple class or any kind of service.

Error Handling and Logging

The Endocore framework provides some basic tools to handle errors and logging.

Using the file logger

From within any Action or Domain you have access to a PSR-3 compatible file logger.

Logger Configuration

Using you configuration file config/config.php you can define the target folder for your log-files as well as the min. log level:

The log files will be stored per day with a filename like 2018-12-12_endocore.log.

Log levels

A PSR-3 compatible logger can log at different levels. All events with a level lower than the min. level defined in your configuration will be dropped. The available log levels are:

There is also a generic log method available:

Additionally it is possible to provide some context information:

Error responses

When using a Responder (typically from within an Action) you can use various methods in case an error occurrs in your application and you need to stop the execution:

This method will automatically respond with an HTTP status code 500 and render a simple error message.

For HTTP errors there are some additional methods which will set there corresponding HTTP status codes automatically:

Throwing exceptions

In case you can not use a responder you are still able to respond with an error message using exceptions. You can throw there exceptions from anywhere in your application.

Generic Exceptions

Throwing a EndocoreException will force the application to respond with an error 500 code. Also the error will be logged to your logfile.

HTTP Exceptions

For each HTTP error supported by a Responder there is a corresponding Exception which you can throw anywhere in your application:

License

MIT