Download the PHP package jeanisahakyan/motion-dots without Composer

MotionDots Documentation

MotionDots is a PHP framework designed to simplify API development by providing tools for dynamic method invocation, input validation, structured responses, and more. It streamlines the process of building APIs by handling common tasks such as parameter validation, response formatting, error handling, and supports the use of native PHP 8.1 enums for robust type definitions.

What is MotionDots?

MotionDots is a lightweight PHP framework that aids in developing APIs by providing:

• Dynamic Method Invocation: Automatically maps API requests to methods in your classes.
• Input Validation: Validates and sanitizes input parameters using custom types.
• Structured Responses: Ensures consistent response formats across your API.
• Error Handling: Simplifies error reporting and handling.
• Enum Support: Utilizes native PHP 8.1 enums for robust type definitions.
• Context Management: Shares data across methods and types during a request.

Purpose and Use Cases

MotionDots is ideal for:

• Developers looking to quickly build robust APIs.
• Projects requiring strict input validation.
• APIs that need consistent response formats.
• Applications where dynamic method routing is beneficial.
• Projects that can benefit from the use of enums for parameter and response type definitions.
• Applications needing a shared context between methods and types.

Getting Started with MotionDots

Installation via Composer

Ensure your PHP version is 8.1 or higher.

Install MotionDots via Composer by adding it to your composer.json or running:

Recommended Project Structure

Organize your project as follows:

Creating the API Processor

The API processor handles incoming requests and routes them to the appropriate methods. Place it in src/YourProcessor.php.

Example YourProcessor.php:

Explanation:

• Setting Context Values:
  • After instantiating the Processor, you can access the Context object using $processor->getContext().
  • Use set() or setMany() methods to set initial context values.
  • These values will be accessible in your methods and types during the request lifecycle.

Then, in your index.php, you can instantiate and use this processor:

Example index.php:

Creating a New API Method

API methods are organized into classes extending AbstractMethod. Each public method in the class becomes an API endpoint.

Defining the Method Class

Create a new class in src/API/Methods/.

Example:

Implementing API Methods

Define public methods in your class using camelCase. The method's name, combined with the class name, forms the API endpoint.

Method: registerUser

Definition:

Usage of Context in Method:

Request Example:

Response Example:

Method: loginUser

Definition:

Request Example:

Response Example:

Method: updateUserStatus

Definition:

Request Example:

Response Example:

Creating a New Response

Responses extend AbstractResponse and define the structure of the data returned to the client. The AbstractResponse class automatically handles JSON serialization of public properties.

Example:

Note: The AbstractResponse class provides default implementations for JSON serialization by automatically including public properties.

Creating a New Parameter Type

Custom parameter types extend AbstractType and handle validation and parsing of input parameters. They have access to the context via $this->context.

Example:

Using Enums

Enums provide a way to define a set of named constants, which can be used for parameter validation and response fields. With PHP 8.1, you can use native enums.

Defining an Enum

Example:

Using Enums in Parameters

Enums can be used as parameter types to ensure that only valid values are passed.

Usage in Method:

Handling API Requests

Requests are handled by the Processor, which invokes the appropriate method based on the request URI.

Error Handling

Throwing Errors

To throw errors in your methods, use the ErrorException class.

Example:

Common Error Codes:

• ErrorException::SCHEMA_METHOD_EXISTS (-1)
• ErrorException::PARAM_UNSUPPORTED (-2)
• ErrorException::PARAM_UNKNOWN_RESOLVER (-3)
• ErrorException::PARAM_REFLECTION_ERROR (-4)
• ErrorException::PARAM_IS_REQUIRED (-5)
• ErrorException::CONTEXT_UNDEFINED_FIELD (-6)
• ErrorException::METHOD_ACTION_UNDEFINED (-7)
• ErrorException::METHOD_UNDEFINED (-8)
• ErrorException::PARAM_INCORRECT (-9)
• ErrorException::INTERNAL_ERROR (-10)
• (Add other error codes as needed)

Handling Errors in the Processor

Errors thrown in your methods are caught in the YourProcessor.php and returned as structured error responses. Example Error Response:

Typescript schema generation

Conventions

If you are going to use typescript api schema generation you have to follow these principles:

• Response class names must be unique
• Enum names used in parameters and response classes must be unique

Structure

Generation

Run php script with content below in you project directory