Easyadmin Mongo Odm Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Bundle

   composer require alterphp/easyadmin-mongo-odm-bundle:dev-master
   

   Ensure easycorp/easyadmin-bundle (v2.0+) is already installed.

2. Configure the Bundle Add the bundle to config/bundles.php:

   return [
       // ...
       AlterPhp\EasyAdminMongoOdmBundle\EasyAdminMongoOdmBundle::class => ['all' => true],
   ];
   

3. Register Documents Define your MongoDB documents in config/packages/easy_admin_mongo_odm.yaml:

   easy_admin_mongo_odm:
       documents:
           App\Document\User:
               class: App\Document\User
               list:
                   fields: ['name', 'email']
   

4. Route to Admin Panel Extend easy_admin.yaml to include menu items:

   easy_admin:
       design:
           menu:
               - { label: 'Users', route: easyadmin_mongo_odm, params: { document: App\Document\User } }
   

5. First Use Case Access /admin (or your custom route) to see the CRUD interface for User documents. Note: Actions like new, edit, and delete are restricted (see Gotchas).

Implementation Patterns

1. Document Configuration

• Basic Fields: Define fields in the list or form sections under each document.

  App\Document\Product:
      class: App\Document\Product
      list:
          fields: ['name', 'price', 'createdAt']
          sort: ['name', 'asc']
  

• Field-Specific Options: Use format (if PropertyConfigPass is implemented in future versions).

  fields:
      - { field: price, format: 'currency' }  # Placeholder for future support
  

2. Integration with EasyAdmin

• Reuse EasyAdmin Features: Leverage EasyAdmin’s filters, search, and bulk actions (where supported).

  App\Document\Order:
      list:
          filters: ['status', 'date']
          search: ['customerName']
  

• Custom Actions: Override templates (e.g., templates/document/crud.html.twig) to add buttons or logic. Example: Add a "Ship" button for Order documents.

3. Workflows

• List View: Automatically renders fields defined in list.fields.
• Edit Form: Fields in form.fields (if configured) populate the edit view.

  form:
      fields: ['name', 'description', 'tags']
  

• Sorting: Defaults to indexed fields only (__SORT_ONLY_INDEXES__). Override in config:

  list:
      sort: ['nonIndexedField', 'asc']  # May impact performance
  

4. Templates

• Override Defaults: Copy templates from vendor/alterphp/easyadmin-mongo-odm-bundle/resources/templates/ to templates/EasyAdminMongoOdmBundle/ in your project. Example: Customize crud.html.twig for document-specific layouts.

5. Associations (Limited)

• Current Limitation: References (@ReferenceOne, @ReferenceMany) are not implemented (__NO_ASSOCIATION__). Workaround: Use embedded documents or manual field rendering for now.

Gotchas and Tips

Pitfalls

1. Restricted Actions

   • new, edit, and delete are disabled by default (__RESTRICTED_ACTIONS__).
   • Workaround: Extend the bundle or use custom routes/controllers for these actions.

2. Sorting Limitations

   • Only indexed fields are sortable for performance (__SORT_ONLY_INDEXES__).
   • Tip: Ensure critical sort fields (e.g., createdAt) are indexed in MongoDB.

3. Missing Features

   • No QueryBuilder Support: Complex queries (e.g., joins) require raw MongoDB queries or manual filtering.

     // Example: Custom repository method
     public function findByStatus(string $status) {
         return $this->createQueryBuilder()->field('status')->equals($status)->getQuery()->execute();
     }
     

   • No format for Fields: Field formatting (e.g., dates, currencies) is not yet supported (PropertyConfigPass TODOs).

4. Template Overrides

   • Twig templates are searched in EasyAdminBundle first. Ensure your overrides are in the correct namespace:

     templates/EasyAdminMongoOdmBundle/document/crud.html.twig
     

5. Menu Items

   • Menu items for documents are not implemented (see TODOs). Use EasyAdmin’s generic menu for now.

Debugging Tips

• Check Routes: Verify routes are generated correctly:

  php bin/console debug:router | grep easyadmin_mongo_odm
  

• Log Queries: Enable MongoDB logging in config/packages/doctrine_mongodb.yaml:

  doctrine_mongodb:
      connections:
          default:
              logging: true
  

• Template Errors: Clear cache after overriding templates:

  php bin/console cache:clear
  

Extension Points

1. Custom Actions Extend the bundle by creating a custom controller or event subscriber to handle actions like new or delete. Example:

   // src/EventListener/MongoOdmActionsListener.php
   public function onKernelRequest(GetResponseEvent $event) {
       if ($event->isMasterRequest() && str_starts_with($event->getRequest()->getPathInfo(), '/admin')) {
           // Add logic for restricted actions
       }
   }
   

2. QueryBuilder Support Contribute to the bundle by implementing QueryBuilder integration (see TODOs). Focus on:

   • Mapping EasyAdmin filters to MongoDB queries.
   • Handling associations via @ReferenceOne/@ReferenceMany.

3. Field Formatting Implement PropertyConfigPass to support field-specific formatting (e.g., dates, enums). Look at EasyAdmin’s PropertyConfigPass for reference.

4. Association Support Add support for @ReferenceOne/@ReferenceMany by extending the bundle’s DocumentMapper or CrudController.

Configuration Quirks

• Case Sensitivity: Document class names in YAML must match exactly (e.g., App\Document\User, not app/document/user).
• Dev vs. Prod: The bundle is experimental. Use in dev environments only for now.
• Symfony UID: The bundle requires symfony/uid (for ID handling), but ensure your documents use Uuid or ObjectId appropriately.