Technical Evaluation

Laravel Alignment: The package (corcel-acf) bridges WordPress Advanced Custom Fields (ACF) with Laravel via Corcel, a Laravel ORM for WordPress. This is a highly strategic fit for projects requiring WordPress data in a Laravel backend (e.g., headless CMS, hybrid apps, or legacy migration).
Abstraction Layer: Provides a clean ORM interface for ACF data, reducing boilerplate for querying custom fields, options, and taxonomies. Aligns with Laravel’s Eloquent conventions.
Use Case Suitability:
- Ideal for decoupling WordPress frontend from Laravel backend (e.g., REST API-driven apps).
- Enables gradual migration of WordPress content to Laravel without rewriting ACF logic.
- Useful for multi-CMS environments where WordPress is a content source.

Prerequisites:
- Requires Corcel (tightenco/corcel) as a dependency, which itself needs wp-data (a WordPress database abstraction layer).
- WordPress Database Access: The Laravel app must connect to the same WordPress database (or a replica) to query ACF data.
- ACF Pro/Plugin Dependency: The WordPress site must have ACF installed (free or Pro) for the package to function.
Laravel Compatibility:
- Works with Laravel 8+ (Corcel’s supported range).
- No direct model binding: ACF data is queried via Corcel’s Post, Option, or Term models, not native Laravel models (unless extended).
Customization:
- Supports custom field serialization (e.g., nested repeater fields) via Corcel’s hasMany/belongsTo relationships.
- Can be extended to map ACF fields to Laravel models (e.g., using accessors/mutators).

Database Coupling:
- Risk: Tight coupling to WordPress DB schema (e.g., wp_postmeta for ACF fields). Schema changes in WordPress (e.g., ACF updates) may break queries.
- Mitigation: Use database migrations to track ACF schema changes or wrap queries in a service layer.
Performance:
- Risk: N+1 queries when fetching ACF data for multiple posts. Corcel mitigates this with eager loading, but complex ACF setups (e.g., nested repeaters) may still be inefficient.
- Mitigation: Implement caching layers (e.g., Laravel’s cache or Redis) for ACF data or use GraphQL (e.g., Laravel GraphQL + Corcel) to optimize payloads.
Data Ownership:
- Risk: ACF data is "owned" by WordPress. Changes in WordPress (e.g., field deletions) may orphan Laravel queries.
- Mitigation: Sync ACF metadata to Laravel (e.g., via a cron job or webhook) or use event listeners to react to WordPress changes.
Testing Complexity:
- Risk: Testing ACF queries requires a WordPress-like database, complicating CI/CD.
- Mitigation: Use database seeding or Dockerized WordPress environments for tests.

WordPress Dependency:
- Is the WordPress site read-only (e.g., static content), or will Laravel write back to ACF? (The package is read-heavy; writes require custom logic.)
Data Freshness:
- What’s the acceptable latency for ACF data in Laravel? (e.g., real-time vs. hourly sync?)
Schema Stability:
- How often does the ACF schema change? (Frequent changes increase maintenance risk.)
Scaling Needs:
- Will ACF data be heavily queried? If so, is caching or denormalization (e.g., storing ACF data in Laravel tables) needed?
Team Skills:
- Does the team have WordPress + Laravel hybrid experience? (Debugging Corcel/ACF issues requires familiarity with both stacks.)
Alternatives:
- Would a custom Laravel model (with raw wp_postmeta queries) or WordPress REST API be simpler for this use case?

Integration Approach

Primary Use Case:
- Headless WordPress: Serve ACF-powered content via Laravel APIs (e.g., for React/Vue frontends).
- Hybrid Apps: Use Laravel for business logic while WordPress handles content.
Stack Compatibility:
- Laravel: Works seamlessly with Eloquent, API routes, and service layers.
- Corcel: Provides WordPress data as Eloquent models (e.g., Post::with('acf')->find($id)).
- ACF: Supports all ACF field types (repeaters, galleries, WYSIWYG) via Corcel’s serialization.
Non-Fit Scenarios:
- Pure Laravel Apps: If no WordPress dependency exists, this package adds unnecessary complexity.
- High-Write Workloads: Not optimized for writing ACF data back to WordPress.

Phase 1: Read-Only Integration
- Install tightenco/corcel and wp4laravel/corcel-acf.
- Query ACF data via Corcel (e.g., Post::find(1)->acf->field_name).
- Example:
```
use Corcel\Models\Post;
$post = Post::with(['acf' => function($query) {
    $query->fields('title', 'custom_field');
}])->find(1);
```
Phase 2: Caching Layer
- Cache ACF data in Laravel’s cache or Redis to reduce DB load.
- Use tags to invalidate cache on WordPress updates (e.g., Cache::tags(['acf'])->put(...)).
Phase 3: Denormalization (Optional)
- For performance, duplicate ACF data into Laravel tables (e.g., acf_fields) and sync via:
  - Database triggers (if both apps write to the same DB).
  - Cron jobs (e.g., wp-cli + Laravel task scheduler).
Phase 4: Write Support (Advanced)
- Extend the package to write ACF data via:
  - Custom Corcel events or direct wp_postmeta updates.
  - WordPress REST API calls from Laravel.

Laravel Versions: Tested with Laravel 8+ (check Corcel’s docs for exact versions).
ACF Versions: Works with ACF 5+ (free/Pro). Test with the same ACF version as the WordPress site.
Database: Requires MySQL/MariaDB (WordPress’s default). PostgreSQL may need adjustments.
Hosting: Compatible with shared hosting (if WordPress DB is accessible) and cloud setups (e.g., Laravel on Heroku + WordPress on AWS RDS).

Prerequisites:
- Set up Corcel (composer require tightenco/corcel).
- Configure wp-data in Laravel’s .env:
```
WP_DATA_DB_CONNECTION=mysql
WP_DATA_DB_DATABASE=wordpress_db
```
Core Integration:
- Publish Corcel’s config (php artisan vendor:publish --tag=corcel-config).
- Test basic ACF queries (e.g., Post::find(1)->acf).
Optimization:
- Add caching for frequent queries.
- Implement eager loading for N+1 issues.
Monitoring:
- Log Corcel queries to identify slow ACF fetches.
- Set up health checks for WordPress DB connectivity.

Dependencies:
- Corcel: Actively maintained (check GitHub).
- ACF Package: Unmaintained fork (original repo by tungpham42 is stale). Risk: Bugs or ACF schema changes may break queries.
- Mitigation:
  - Monitor for upstream Corcel/ACF updates.
  - Fork the package and apply fixes if needed.
Schema Drift:
- ACF field additions/deletions require Laravel query updates.
- Solution: Use dynamic field queries (e.g., Post::with(['acf' => function($query) use ($fields) { ... }])).
Documentation:
- Limited docs: Relies on Corcel’s documentation. May need internal runbooks for ACF-specific queries.