Download the PHP package firehed/api without Composer

On this page you can find all versions of the php package firehed/api. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.

FAQ

After the download, you have to make one include require_once('vendor/autoload.php');. After that you have to import the classes with use statements.

Example:
If you use only one package a project is not needed. But if you use more then one package, without a project it is not possible to import the classes with use statements.

In general, it is recommended to use always a project to download your libraries. In an application normally there is more than one library needed.
Some PHP packages are not free to download and because of that hosted in private repositories. In this case some credentials are needed to access such packages. Please use the auth.json textarea to insert credentials, if a package is coming from a private repository. You can look here for more information.

  • Some hosting areas are not accessible by a terminal or SSH. Then it is not possible to use Composer.
  • To use Composer is sometimes complicated. Especially for beginners.
  • Composer needs much resources. Sometimes they are not available on a simple webspace.
  • If you are using private repositories you don't need to share your credentials. You can set up everything on our site and then you provide a simple download link to your team member.
  • Simplify your Composer build process. Use our own command line tool to download the vendor folder as binary. This makes your build process faster and you don't need to expose your credentials for private repositories.
Please rate this library. Is it a good library?

Informations about the package api

API Framework

Build Status codecov

Installation

API is available via composer:

composer require firehed/api

Usage

Set up an .apiconfig file, which contains JSON-formatted settings for the framework. You may run vendor/bin/api generate:config to do this. See configuration below for additional information.

Generate a default front-controller:

vendor/bin/api generate:frontController

After creating, modifying, or deleting endpoints, run the compiler:

vendor/bin/api compile:all

This step is not optional: the framework depends on the generated files, rather than ever attempting to perform the same step at runtime. It is expected that you will rebuild the files on every build/deployment with the above command. See the section on best practices below.

Testing

For convenience, a trait is included that includes tests for the description methods of your endpoints. In your test case class (which typically extends PHPUnit\Framework\TestCase, use the trait:

\Firehed\API\Traits\EndpointTestCases

And add a getEndpoint method that returns an instance of the endpoint under test.

Example

Configuration

Place a file named .apiconfig in your project root. It uses JSON for the format. There is a console command included to walk you through configuration, which can be invoked by running vendor/bin/api generate:config.

Options

source: required string

The source code directory to scan for API endpoints. Most commonly src.

namespace: required string

A namespace to filter on when searching for endpoints.

webroot: required string

The directory to place a generated front controller. The value should be relative to the project root.

container: optional string

The path to a file which returns a PSR-11-compliant container for config values.

Container

If you set a container value in .apiconfig, the API will be made aware of the container (if you do not use the generated front controller, you may also do this manually). This is how to configure API endpoints at runtime. By convention, if the container has() an endpoint's fully-qualified class name, the dispatcher will get() and use that value when the route is dispatched. If no container is configured, or the container does not have a configuration for the routed endpoint, the routed endpoint will simply be instantiated via new $routedEndpointClassName.

Other auto-detected container entries:

Key Usage Detected
Psr\Log\LoggerInterface Internal logging generated front controller
Firehed\API\Authentication\ProviderInterface Authentication Provider Always if an AuthorizationProvider is set
Firehed\API\Authorization\ProviderInterface Authorization Provider Always if an AuthenticationProvider is set
Firehed\API\Errors\HandlerInterface Error Handler Always

Example

.apiconfig:

config.php:

In this example, when your UserPost endpoint is routed, it will use the endpoint defined in the container - this allows for endpoints with required constructor arguments or other configuration.

If you have e.g. a UserGet endpoint which is not in the container, the dispatcher will automatically attempt to instantiate it with new. If that endpoint has no constructor arguments, this will be fine. However, this means your application will crash at runtime if it does - so any endpoints with required constructors must be configured in the container.

Authentication and Authorization

There are two interfaces defined for the processes of authentication (who is performing the request) and authorization (whether they are allowed to perform the request), respectively named Authentication\ProviderInterface and Authorization\ProviderInterface. Both interfaces will be autodetected in a container, and both must be provided. If both of these are not provided, no authentication or authorization will ever be performed using the application-wide handlers.

Any endpoint that implements Interfaces\AuthenticatedEndpointInterface will have these processes performed prior to execution, and the container returned by the Authentication provider will be made available to it. If an endpoint does not implement Interfaces\AuthenticatedEndpointInterface (i.e. it only implements Interfaces\EndpointInterface), application-wide auth will be skipped. Endpoints may, of course, choose to implement their own auth protocols in their execute() method, but this is discouraged, with the exception of login-type pages (see below).

Generally speaking, implementations for the above interfaces should be looking for authentication data present in (almost) every request: cookies, OAuth Bearer tokens, HTTP basic auth, etc., and validating their authenticity. Endpoints that are used to obtain auth data (e.g. OAuth grant) typically will NOT be authenticated themselves, but will set or return the data to be used to authenticate other requests.

Example provider, which implements both interfaces:

Error Handling

It is strongly discouraged to handle most exceptions that are thrown in an Endpoint's execute() method. Instead, prefer to write services that fail loudly by throwing exceptions and endpoints that expect the success case. This is not an absolute rule, but helps avoid deeply-nested try/catch blocks and other complexity around error handling.

The API framework is responsible for catching all exceptions thrown during an Endpoint's execute() method, and will provide them to dedicated exception handlers.

It is highly recommended to create and provide a default error handler, Firehed\API\Errors\HandlerInterface, via the container (see table above). All unhandled exceptions will be sent to that handler, along with the request (so that responses can be formatted according to Accept headers, etc).

All endpoints that implement Firehed\API\Interfaces\HandlesOwnErrorsInterface (which is a part of EndpointInterface prior to v4.0.0) will have their handleException() method called with the thrown exception. This handler will be called before the default error handler. This method may choose to ignore certain exception classes (by rethrowing them), but must return a PSR ResponseInterface when opting to handle an exception.

Finally, a global fallback handler is configured by default, which will log the exception and return a generic 500 error.

Best Practices

Source Control

Use source control, of course.

The following patterns should be added to your source control's ignored files, to exclude generated files:

Build Automation

It is highly recommended (for any modern PHP application) to use automated builds.

This framework relies on compilation in order to improve performance. You must run the compilation process prior to deployment, and should do so during your automated build:

vendor/bin/api compile:all.

Docker

There are no special requirements to run in Docker, beyond what is noted in the above build automation section.

This means you should have the following line in your Dockerfile at any point after installing dependencies with Composer:

You should also add all of the source control ignore files to your .dockerignore.

Compatibility

This framework tries to strictly follow the rules of Semantic Versioning. In summary, this means that given a release named X.Y.Z:

The term "breaking changes" should be interpreted to mean:

Breaking changes DO NOT include:

Whenever possible, deprecated functionality will be marked as such by trigger_error(string, E_USER_DEPRECATED) (in addition to release notes). Note that depending on your PHP settings, this may result in an ErrorException being thrown. Since that is a configurable behavior, it is NOT considered to be a BC break.

Additionally, the entire Firehed\API namespace should be considered reserved for the purposes of PSR-11 Container auto-detection. That is to say, if you use a key starting with Firehed\API in your container, you should expect that key may be retrieved and used without explicitly opting-in to the behavior it provides.


All versions of api with dependencies

PHP Build Version
Package Version
Requires php Version ^7.0
firehed/common Version ^1.0
firehed/input Version ^2.0
psr/container Version ^1.0
psr/http-message Version ^1.0
psr/http-server-handler Version ^1.0
psr/http-server-middleware Version ^1.0
psr/log Version ^1.0
zendframework/zend-diactoros Version ^1.3 || ^2.0
Composer command for our command line client (download client) This client runs in each environment. You don't need a specific PHP version etc. The first 20 API calls are free. Standard composer command

The package firehed/api contains the following files

Loading the files please wait ....