Advanced Features

Advanced Features

This page surveys framework components for larger applications. Integrations are optional and require application configuration; do not assume a service is active because its classes are present.

Dependency container

Machinjiri includes a container and helper functions for resolving dependencies. Base controllers can resolve request, response, session, cookie, CSRF, and filesystem services. Prefer constructor injection and explicit interfaces for application services where the app's container configuration supports them.

Keep service registration in application bootstrap/providers rather than hiding global state in route handlers. Test components with explicit dependencies so that behavior stays predictable.

Service providers

Providers organize service registration and bootstrap work. The framework has a provider loader, base ServiceProvider, and CLI provider-management commands. Register providers according to your application's generated configuration and lifecycle.

Providers should be idempotent and avoid expensive work on every request. Keep irreversible setup, such as schema changes, in migrations rather than provider boot methods.

Events

The event subsystem includes events, listeners, subscribers, and queueable listeners. Use events to decouple side effects from the operation that produced them, for example sending a notification after a domain action.

Document event names and payload shape, and decide whether each listener must run synchronously or may be queued. Ensure important database changes and their emitted events cannot become inconsistent; use an outbox or other durable pattern when delivery guarantees matter.

Caching

Cache components include manager/store contracts and array, file, and Redis stores, plus tagged caching and metrics support. Use cache for derived/retrievable data, not as the only copy of critical state.

Cache design checklist:

• Define a stable key and expiration appropriate to the data.
• Invalidate or version keys when source data changes.
• Avoid storing secrets or user-specific values under shared keys.
• Consider stampedes for expensive, popular keys.
• Use Redis only after adding/configuring its client and service.

The package suggests Predis as an optional dependency; install/configure it only if using a Redis-backed feature.

Queues and workers

The queue subsystem exposes job, dispatcher, processor, queue, and worker contracts, with sync, memory, file, database, and Redis drivers represented in source. A production worker needs durable configuration and a process manager appropriate to the deployment.

The generated application's CLI may offer commands including:

php artisan queue:init
php artisan queue:work
php artisan queue:status
php artisan queue:failed
php artisan queue:retry

Use php artisan list and each command's help in the app to confirm arguments. Design jobs to be retry-safe: a job may run more than once. Set timeouts and retry limits intentionally, monitor failed work, and do not put credentials in serialized payloads.

Task scheduling

The framework contains task-scheduling components and CLI operations such as scheduler:list, scheduler:run, and scheduler:status. The deployment must actually invoke the scheduler according to your chosen design (for example, a system scheduler or long-running process). Verify locking and duplicate-run behavior before running multiple scheduler instances.

The dragonmantank/cron-expression package is optional and suggested by Composer; install it only if your scheduling setup needs it.

HTTP client, webhooks, notifications

The framework includes HTTP client/request/response classes and components for webhooks, mail, SMS, and database notifications. These are integration points, not proof that credentials or provider accounts exist.

• Set timeouts for outbound HTTP.
• Verify webhook signatures before trusting their payload.
• Make webhook handlers idempotent and return promptly.
• Avoid logging sensitive payload fields.
• Treat provider failures as normal operational outcomes and surface them to logs/metrics.

Filesystems and uploads

The filesystem area contains local/adaptor/cloud components. Choose storage based on the deployment and backup strategy. Validate uploads, generate server-side names, enforce size limits, and avoid serving untrusted uploads as executable content.

Performance and observability

Machinjiri includes logging, cache metrics, timers, profiling, memory tracking, and performance-related components. Instrument a real workload before optimizing. Collect enough context to troubleshoot while excluding credentials and personal data from logs.

Extending the framework

When writing reusable functionality:

1. Define a contract before coupling to a concrete adapter.
2. Register the implementation through the application container/provider.
3. Keep configuration explicit and validate it early.
4. Test failure and retry paths, not only the success case.
5. Document which packages, extensions, and external services are optional prerequisites.

See CLI and Operations for the included command families.