Core Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require apie/core
   

   Ensure your composer.json includes "minimum-stability": "dev" if using unstable versions.

2. First Use Case: Attribute-Based Annotations Apie/core primarily provides attributes and interfaces for API/endpoint definitions. Start by annotating a class or method:

   use Apie\Core\Attributes\ApiEndpoint;
   
   #[ApiEndpoint(path: '/users', methods: ['GET'])]
   class UserController {
       // ...
   }
   

3. Where to Look First

   • Attributes: Check src/Attributes/ for available annotations (e.g., ApiEndpoint, ApiRequest, ApiResponse).
   • Interfaces: Review src/Contracts/ for core interfaces like ApiEndpointInterface or ApiRequestInterface.
   • Examples: Browse the monorepo’s examples/ for practical usage.

Implementation Patterns

1. Attribute-Driven Development

• Endpoint Definition: Use #[ApiEndpoint] to define routes/methods. Combine with #[ApiRequest]/#[ApiResponse] for input/output schemas:

  #[ApiEndpoint(path: '/users/{id}', methods: ['GET'])]
  #[ApiResponse(type: User::class)]
  public function show(int $id): User { ... }
  

• Request Validation: Leverage #[ApiRequest] to enforce request body/params validation via PHP types or custom validators:

  #[ApiRequest(type: CreateUserRequest::class)]
  public function store(CreateUserRequest $request) { ... }
  

2. Integration with Laravel

• Service Provider Binding: Bind Apie’s core interfaces to Laravel’s container in AppServiceProvider:

  $this->app->bind(
      Apie\Core\Contracts\ApiEndpointResolver::class,
      Apie\Core\Resolvers\LaravelEndpointResolver::class
  );
  

• Route Registration: Use Apie’s RouteRegistrar to auto-discover and register endpoints:

  $registrar = new Apie\Core\RouteRegistrar();
  $registrar->register(app(ApiEndpointResolver::class));
  

3. Custom Attributes

Extend Apie’s functionality by creating custom attributes:

use Apie\Core\Attributes\ApiAttribute;

#[Attribute(Attribute::TARGET_METHOD)]
class RateLimited implements ApiAttribute {
    public function __construct(public int $limit) {}
}

Register them via Apie\Core\AttributeRegistry.

4. Middleware Integration

Attach Apie-specific middleware (e.g., auth, rate-limiting) to annotated endpoints:

#[ApiEndpoint(middleware: [AuthMiddleware::class])]
public function sensitiveData() { ... }

5. Testing Patterns

• Mock ApiEndpointResolver to test endpoint resolution:

  $resolver = Mockery::mock(ApiEndpointResolver::class);
  $resolver->shouldReceive('getEndpoints')->andReturn([...]);
  

• Use Apie\Core\Testing\Assert for API response assertions:

  $this->assertApiResponse(200, User::class, $response);
  

Gotchas and Tips

Pitfalls

1. Attribute Target Mismatches:

   • Ensure attributes are applied to correct targets (e.g., #[ApiEndpoint] on classes/methods, not properties).
   • Fix: Use Attribute::TARGET_CLASS_METHOD in custom attributes.

2. Circular Dependencies:

   • Apie/core is part of a monorepo. Avoid mixing stable/unstable versions across apie/* packages.
   • Fix: Pin all apie/* packages to the same version in composer.json.

3. Laravel Route Conflicts:

   • Apie’s auto-registration may override manual routes. Use #[ApiEndpoint(priority: -100)] to control order.
   • Fix: Explicitly exclude routes with #[IgnoreRoute].

4. PHP 8.0+ Requirements:

   • Apie/core requires PHP 8.0+. Attributes and union types may fail on older versions.
   • Fix: Update PHP or use a polyfill like ramsey/uuid.

Debugging Tips

• Enable Verbose Logging: Configure Apie’s logger via config/apie.php:

  'debug' => env('APIE_DEBUG', false),
  

• Inspect Resolved Endpoints: Dump the resolver’s output:

  dd(app(ApiEndpointResolver::class)->getEndpoints());
  

• Attribute Reflection: Use ReflectionClass::getAttributes() to debug missing/incorrect attributes.

Extension Points

1. Custom Resolvers: Implement ApiEndpointResolverInterface to override default endpoint resolution logic (e.g., for dynamic routes).

2. Request/Response Transformers: Extend Apie\Core\Transformers\JsonTransformer to customize serialization/deserialization.

3. Event Listeners: Listen to Apie\Core\Events\EndpointRegistered to react to new endpoints (e.g., for analytics):

   Event::listen(EndpointRegistered::class, function ($event) {
       Log::info("Registered endpoint: {$event->endpoint->path}");
   });
   

Performance Quirks

• Attribute Reflection Overhead: Heavy use of attributes may impact route loading time. Cache resolved endpoints:

  $resolver->setCache(new FileCache(storage_path('framework/cache/apie')));
  

• Validation Performance: Complex #[ApiRequest] types (e.g., nested objects) can slow validation. Use DTOs sparingly.

Config Tricks

• Disable Auto-Discovery: Set 'discovery' => false in config/apie.php to manually register endpoints.
• Custom Attribute Namespaces: Whitelist namespaces in 'attribute_namespaces' to restrict which attributes are processed.

```markdown
### **Community Notes**
- **Monorepo Workflow**:
  Contribute via the [apie-lib-monorepo](https://github.com/apie-lib/apie-lib-monorepo). Core issues are tagged `package:core`.
- **Slack/Discord**:
  Join the [Apie community](https://apie-lib.github.io/community) for support.