Download the PHP package jeanisahakyan/motion-dots without Composer

MotionDots

MotionDots is a lightweight PHP framework designed to simplify API development by providing tools for dynamic method invocation, input validation, structured responses, and TypeScript generation. 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.

✨ Key Features

• 🚀 Dynamic Method Invocation: Automatically maps API requests to methods in your classes
• 🛡️ Type Safety: Validates and sanitizes input parameters using custom types
• 📋 Structured Responses: Ensures consistent response formats across your API
• ⚡ Error Handling: Comprehensive error system with predefined error codes
• 🔧 Enum Support: Native PHP 8.1 enums for robust type definitions
• 🔄 Context Management: Shares data across methods and types during a request
• 📱 TypeScript Generation: Automatic TypeScript definitions for frontend integration
• 🔍 System Methods: Built-in introspection and utility methods

🎯 Perfect For

• API Developers looking to quickly build robust APIs
• Projects requiring strict input validation and type safety
• Teams needing consistent response formats across endpoints
• Applications where dynamic method routing is beneficial
• Frontend Teams requiring TypeScript integration
• Systems needing shared context between methods and types

📚 Documentation

For comprehensive documentation, visit our Documentation Index:

• Quick Start Guide - Get up and running quickly
• Architecture Overview - Understand the system design
• API Reference - Complete API documentation
• Examples & Patterns - Real-world usage examples
• TypeScript Integration - Frontend type generation

🚀 Quick Start

Requirements

• PHP 8.1+ (required for enum support and modern features)
• Composer for dependency management
• JSON extension (usually included with PHP)

Installation

Install MotionDots via Composer:

Basic Setup

Create a simple API endpoint in just a few lines:

📖 Need more details? Check out our Complete Quick Start Guide for detailed setup instructions.

Project Structure

🔧 Core Concepts

API Methods

Create API endpoints by extending AbstractMethod:

Custom Types

Build type-safe parameters with validation:

Response Classes

Structure your API responses:

📖 Learn more: See our Response System documentation.

🛠️ Advanced Setup

Complete API Processor

📖 Detailed Examples

Creating API Methods

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

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 Generation

Generate TypeScript definitions automatically for frontend integration:

This creates organized TypeScript files:

⚡ Error Handling

MotionDots provides comprehensive error handling with predefined error codes:

Common Error Codes:

• PARAM_INCORRECT (-9) - Parameter validation failed
• PARAM_IS_REQUIRED (-5) - Required parameter missing
• METHOD_UNDEFINED (-8) - Method not registered
• INTERNAL_ERROR (-10) - System error

🎯 What's Next?

Ready to dive deeper? Check out our comprehensive documentation:

• 📚 Complete Documentation - Full documentation index
• 🚀 Quick Start Guide - Detailed setup instructions
• 🏗️ Architecture Overview - System design and patterns
• 📖 API Reference - Complete API documentation
• 💡 Examples & Patterns - Real-world usage examples
• 🔧 TypeScript Integration - Frontend type generation
• 🛡️ Type System - Custom types and validation
• 📋 Response System - Response formatting and serialization

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

📞 Support

• 📖 Documentation: Check our comprehensive docs
• 🐛 Issues: Report bugs on GitHub Issues
• 💡 Questions: Open a discussion for questions and ideas

MotionDots - Building robust APIs with PHP 8.1+ features, type safety, and automatic TypeScript generation. 🚀