Download the PHP package aliengen/pachyderm without Composer

Pachyderm - A Micro PHP Framework for APIs

Pachyderm is a lightweight PHP framework designed for building APIs with ease. It provides a simple and flexible way to manage routes, middleware, and HTTP requests.

Table of Contents

• Introduction
  • Motivation
  • Goals
  • Features
• Getting Started
  • Installation
  • Usage
  • Simple Example
  • Setting Up a Controller
• Middleware
  • Registering Global Middleware
  • Adding and Removing Middleware for Specific Routes
• Routes
  • Supported HTTP Methods
• Services
  • Registering a Service
  • Using a Registered Service
  • Direct Instantiation of Db
• Exception Handling
  • Using ExceptionHandlerMiddleware
  • Existing Exceptions
• Additional Information
• License

Introduction

Motivation

Pachyderm began as an internal training project at AlienGen, aimed at deepening our understanding of framework fundamentals and showcasing PHP's capabilities. As we developed numerous microservices, we recognized the need for a more robust solution than single-file scripts for main endpoints. Pachyderm emerged as a micro framework designed to be both simple and user-friendly, offering a lightweight alternative to larger frameworks like Laravel or Symfony.

We adhere to the KISS (Keep It Simple, Stupid) principle, ensuring our code remains straightforward and comprehensible. The framework's components are extensible, allowing for customization to meet specific needs. By minimizing external dependencies, Pachyderm remains compact and tailored.

Our development approach aligns with the 12-factor app principles, ensuring the framework is built to support these best practices.

Goals

• Developer Experience: Prioritize ease of use, enabling developers to concentrate on business logic with minimal code.
• Simplicity: Maintain clear and understandable code for developers.
• Extensibility: Allow customization to suit individual project requirements.
• Lightweight: Core framework avoids external dependencies, though projects can incorporate any necessary libraries.

Features

• Routing
• Service Container
• Validation
• Middleware
• Exception Handling
• Response Management

Getting Started

Installation

To install Pachyderm, use Composer:

Usage

Simple Example

Setting Up a Controller

To create a controller, you need to set up a dispatcher and register your middleware and routes.

Middleware

Middleware in Pachyderm allows you to process requests and responses. You can register global middleware or specific middleware for individual routes.

Registering Global Middleware

Example of registering global middleware:

Adding and Removing Middleware for Specific Routes

You can add middleware that should only be applied to specific routes, or remove global middleware from specific routes.

Example of adding and removing middleware for a route:

• Local Middleware: Specify middleware that should only be applied to the route by passing an array of middleware classes as the third parameter.

• Blacklist Middleware: Specify global middleware that should be excluded from the route by passing an array of middleware classes as the fourth parameter.

Routes

Pachyderm supports various HTTP methods such as GET, POST, PUT, DELETE, etc. You can define routes and their corresponding handlers.

Supported HTTP Methods

• GET: Used to retrieve data from the server.

• POST: Used to send data to the server.

• PUT: Used to update existing data on the server.

• DELETE: Used to delete data from the server.

• OPTIONS: Used to describe the communication options for the target resource.

• HEAD: Used to retrieve the headers of a resource.

Services

Pachyderm provides a simple service container for managing service instances. You can register services as closures and retrieve them by name.

Registering a Service

To register a service, use the Service::set method. For example, to register the Db class as a service:

Using a Registered Service

To retrieve and use a registered service, use the Service::get method. For example, to use the Db service:

Direct Instantiation of Db

If you prefer to create a new instance of the Db class directly, you can do so as follows:

This approach allows you to have multiple instances of the Db class with different configurations if needed.

Exception Handling

Pachyderm provides a way to handle exceptions that occur during the execution of your application using the ExceptionHandlerMiddleware. This middleware is designed to catch exceptions of type AbstractHTTPException and return a structured response.

Using ExceptionHandlerMiddleware

To use the ExceptionHandlerMiddleware, you need to register it with your dispatcher. This middleware will catch any exceptions that occur during the request processing and handle them appropriately.

Here's an example of how to register and use the ExceptionHandlerMiddleware:

Existing Exceptions

The following exceptions implement the AbstractHTTPException and can be used to handle specific HTTP error scenarios:

• BadRequestException: Represents a 400 Bad Request error.
• UnauthenticatedException: Represents a 401 Unauthorized error.
• NotFoundException: Represents a 404 Not Found error.

These exceptions can be thrown within your route handlers to trigger the ExceptionHandlerMiddleware and return appropriate HTTP error responses.

Additional Information

• Configuration: Use the Config class to manage application configurations.
• Database: The Db class provides methods for database interactions, including transactions and queries.
• Error Handling: Custom exceptions are available for handling different error scenarios.

For more detailed documentation, please refer to the source code and comments within the files.

License

Pachyderm is licensed under the MIT License. See the LICENSE file for more details.