Metabox Bridge Laravel Package

Getting Started

• Install the package via Composer and confirm pollora/metabox 3.1+ is present; v1.1.0 requires it.
• Publish the config: php artisan vendor:publish --tag=metabox-config. This creates config/metabox.php.
• Look first at config/metabox.php for default block category, block mode, block views, and default field group priority. Then check the package service provider if you need to understand discovery paths.
• First use case: annotate a class with #[FieldGroup] to attach custom fields to an existing Pollora post type, or #[Block] to render a Blade-backed block. Place classes in the conventional discovery directory (e.g. app/WordPress/Metaboxes, app/WordPress/Blocks, app/WordPress/Settings) or whatever path the package scans.
• Quick win: create a FieldGroup for a Pollora post type you already have, then verify it appears in the WordPress editor.

Implementation Patterns

• Attribute-driven registration: define plain PHP classes with #[FieldGroup], #[Block], or #[SettingsPage]. The package discovers and registers them automatically—no manual register_* calls.
• Field groups: target Pollora post types and taxonomies directly in the attribute. Example: #[FieldGroup(id: 'book_details', title: 'Book Details', postTypes: ['book'])]. Use Pollora slugs or class references as targets.
• Blocks: declare #[Block(id: 'hero', namespace: 'app', title: 'Hero')]. The package renders the block with a Blade view named after the namespace and ID (e.g. app::hero or app.hero—confirm the resolver convention). Keep the view in resources/views.
• Settings pages: declare #[SettingsPage(id: 'my_settings', title: 'My Settings')] and follow Pollora/metabox field conventions for the page contents.
• Container-managed classes: attribute classes are resolved from the Laravel container, so constructor injection works. Use this for services, repositories, or config access.
• Idempotent discovery: classes are registered once even if Pollora triggers discovery multiple times. Avoid adding duplicate manual registrations.
• Config defaults: set default_block_category, default_block_mode, default_block_views, and default_field_group_priority in config/metabox.php to standardize behavior. Override per attribute where needed.
• Organize by concern: keep field groups, blocks, and settings pages in separate namespaces/directories so discovery is predictable and debugging is easier.
• Invalid declarations: if one attribute class is malformed, the package reports it and continues discovering the rest. Check logs for the specific class instead of assuming discovery is broken globally.

Gotchas and Tips

• Version compatibility: v1.1.0 requires pollora/metabox 3.1. Check your installed version before upgrading; older versions may not support the attribute APIs.
• Discovery paths: if classes are not registered, verify the package is scanning the correct namespace/directory. Run composer dump-autoload after moving classes.
• Block view naming: a block will fail to render if the Blade view does not match the namespace/ID convention. Double-check the resolved view name; use default_block_views for fallbacks.
• Non-fatal invalid declarations: a typo in an attribute argument will not crash the app, but the metabox/block/settings page will silently not appear. Search logs for discovery warnings and validate attribute syntax.
• Registered once: if you see duplicates, check that you are not also registering the class manually via Pollora/metabox. The idempotent registration is intentional.
• Config cache: after editing config/metabox.php, run php artisan config:clear locally or config:cache in production. Stale config is a common cause of defaults not applying.
• Field group priority: the default comes from config; override per field group when you need a specific editor placement. Do not rely on registration order.
• Container pitfalls: because classes are container-resolved, keep attribute arguments scalar/array and avoid static state. Constructor dependencies should be resolvable services.
• Debugging discovery: inspect the package service provider for discovery bindings or events. If a registry is exposed, use Tinker to confirm which classes were discovered.
• Extension points: config defaults and attribute parameters are the primary extension points. Check the service provider for bindings/events before editing vendor code.