Download the PHP package locky42/leopard-core without Composer

Leopard Core

leopard-core is the core library for the Leopard Framework, providing essential features such as routing, attributes, dependency injection container, and other foundational components.

Table of Contents

• Installation
• Core Components
  • Dependency Injection Container
  • Routing
  • Attributes
  • ContractFactory
  • View
  • SEO
• Usage Examples
• Testing

Installation

Install leopard-core using Composer:

Core Components

Dependency Injection Container

The Container is a simple dependency injection container that allows you to register services and retrieve their instances.

Example:

Routing

The Router allows you to define routes using attributes, YAML configuration, and automatic route generation based on controller structure.

Routing Methods

1. Attribute-based routing - Define routes using PHP attributes
2. YAML configuration - Define routes and controller paths in YAML
3. Auto-routing - Automatic route generation for methods ending with Action suffix

Action Method Convention

For auto-routing (YAML controllers), only methods ending with Action suffix are processed as routes:

• HTTP method prefix: get, post, put, delete, patch, options, head
• Default method: If no prefix is specified, GET is used by default
• Action name: Formed by removing the HTTP method prefix (if any) and the Action suffix

Examples:

Attribute-based Routing Example:

YAML Configuration Example:

YAML Controllers Behavior

• controllers[].controller registers one конкретний контролер (relative to App\\Controllers\\..., or absolute FQCN if it starts with \\).
• controllers[].namespace scans all *Controller.php in src/Controllers/{Namespace} and registers them with the same base path.
• Only methods ending with Action are auto-routed from YAML controller definitions.
• HTTP method prefix is detected from method name: get|post|put|delete|patch|options|head.
• Special path handling for path:
  • path: / → /{controller} and /{controller}/{action}
  • path: "" → / and /{action}
  • path: /base → /base/{controller} and /base/{controller}/{action}

Dynamic Parameters in Paths

The router supports these placeholders in route paths:

• {id} - one URI segment (no slash)
• {id:\\d+} - custom regex constraint
• {path} - greedy capture including /

If a parameter type in controller method is int|float|bool and conversion fails, router returns 404.

HEAD requests are allowed to match GET routes.

Auto-routing with loadControllersFrom:

Attributes

leopard-core supports PHP attributes for defining routes and other metadata.

Example:

ContractFactory

The ContractFactory is a universal factory for creating instances through interface contracts. It enables flexible dependency management by allowing you to register and swap implementations without modifying existing code.

Key Benefits:

• Flexibility - Easily swap implementations
• Testability - Create mock objects for testing
• Extensibility - Add custom implementations
• Dependency Inversion - Depend on abstractions, not concrete classes

Basic Usage:

Swapping Implementations:

Available Methods:

• register(string $interface, string $className, array $doctrineMapping = []): void - Register an implementation (and sync Doctrine mapping when available)
• create(string $interface): object - Create an instance
• getMapping(string $interface): ?string - Get registered class name
• hasMapping(string $interface): bool - Check if interface is registered
• getMappings(): array - Get all registered mappings
• unregister(string $interface): bool - Unregister an interface
• clear(): void - Clear all mappings
• reset(): void - Reset to initial state

Integration Example:

Doctrine Integration (auto ResolveTargetEntity)

If locky42/leopard-doctrine is installed, ContractFactory::register(...) automatically forwards the mapping to ResolveTargetEntityRegistry::addResolveTargetEntity(...).

You can also pass Doctrine mapping options as the third argument:

In application projects, keep all contract mappings in one file (for example config/contract-mappings.php) and include it in bootstrap.

Best Practices:

1. Always use ::class syntax:

2. Register at application bootstrap:

3. Use type hints with interfaces:

4. Clear mappings in tests:

Error Handling:

The factory throws InvalidArgumentException in these cases:

• Class doesn't exist
• Interface doesn't exist
• Class doesn't implement the interface
• No mapping found when creating instance

View

The View class is responsible for rendering templates and managing the presentation layer. It supports layouts, blocks, and integration with the SEO service.

Features:

• Template rendering with data passing
• Layout system for consistent page structure
• Block rendering for reusable components
• CSS and JavaScript management
• SEO metadata through integrated Seo service

Example:

Rendering Blocks:

SEO

The Seo service manages SEO metadata for your pages, including meta tags, Open Graph, Twitter Cards, and more.

Features:

• Meta tags management
• Open Graph tags for social media
• Twitter Cards support
• Canonical URLs
• Keywords management
• Robots directives
• Charset configuration

Example:

Rendering SEO Tags in Layout:

Usage Examples

Loading Configuration

Testing

To run tests, use the following command:

The tests are located in the vendor/locky42/leopard-core/tests directory.

License

This project is licensed under the MIT License.