CRUD Generator Guide

Comprehensive Usage Example: Building a “Support Ticket” Module

Goal: Scaffold a full CRUD interface for managing support tickets. 1. The All-in-One YAML Definition File Create a file named support_ticket_module.yml somewhere in your project (e.g., in a crud_definitions/ directory).

# crud_definitions/support_ticket_module.yml

# --- Module-level Info (used by `make:module-crud`) ---
name: Ticket
namespace: Support

inertia_crud: # Options for make:inertia-crud
  softDeletes: true

vue_form: # Options for make:vue-form
  formName: TicketForm
  withLayout: true # Use sections for form layout

vue_dataview: # Options for make:vue-dataview
  componentName: TicketDetailView

zod_schema: # Options for make:zod-schema
  yamlKey: schema_fields # The key in *this file* holding the Zod schema definition

#-------------------------------------------------------------------------------
# ZOD SCHEMA FIELDS DEFINITION
#-------------------------------------------------------------------------------
schema_fields:
  - { model: id, type: string }
  - { model: subject, type: string, required: true }
  - { model: content, type: string, optional: true, nullable: true }
  - { model: priority, type: enum, options: [low, medium, high], default: "medium" }
  - { model: status, type: string, default: "open" }
  - { model: isResolved, type: boolean, default: false }
  - { model: assignedAgentId, type: string, nullable: true, optional: true }
  - { model: satisfactionRating, type: number, min: 1, max: 5, optional: true, nullable: true }
  - { model: reportedAt, type: datetime, default: "now" }
  - { model: deadline, type: date, optional: true, nullable: true }
  - { model: attachments, type: attachmentupload, optional: true }
  - { model: customerSignature, type: signature, optional: true, nullable: true }
  - { model: issueLocation, type: location, optional: true, nullable: true }
  - { model: affectedArea, type: geofence, optional: true, nullable: true }
  - { model: relatedTasks, type: array_object_manager, optional: true }

#-------------------------------------------------------------------------------
# TABLE COLUMN DEFINITIONS (for Index.vue)
#-------------------------------------------------------------------------------
table:
  - { name: id, label: "Ticket ID", show: true, sort: true, search: true }
  - { name: subject, label: "Subject", show: true, search: true, sort: true }
  - { name: status, label: "Status", show: true, filter: true, sort: true, datatype: "statusBadge" }
  - { name: priority, label: "Priority", show: true, filter: true, sort: true, datatype: "badge" }
  - { name: isResolved, label: "Resolved", show: true, sort: true, datatype: "booleanIcon" }
  - { name: assignedAgentName, label: "Agent", show: true, search: true, sort: true } # A related field
  - { name: reportedAt, label: "Reported At", show: true, sort: true, datatype: "datetime" }

#-------------------------------------------------------------------------------
# FORM DEFINITION (for Create.vue / Edit.vue)
#-------------------------------------------------------------------------------
form:
  - label: "Ticket Details"
    name: ticketDetailsSection
    type: card
    children:
      - { label: "Subject", name: subject, model: subject, type: text, validator: "required|min:5", placeholder: "Briefly describe the issue..." }
      - { label: "Status", name: status, model: status, type: select, default: "open", param: { options: [{value: 'open', label: 'Open'}, {value: 'in_progress', label: 'In Progress'}, {value: 'closed', label: 'Closed'}] } }
      - { label: "Priority", name: priority, model: priority, type: radio, default: "medium", param: { options: [{value: 'low', label: 'Low'}, {value: 'medium', label: 'Medium'}, {value: 'high', label: 'High'}] } }
      - { label: "Is Resolved?", name: isResolved, model: isResolved, type: switch }
      - { label: "Deadline", name: deadline, model: deadline, type: datepicker }

  - label: "Issue Description & Attachments"
    name: descriptionSection
    type: card
    children:
      - { label: "Full Description", name: content, model: content, type: textarea, param: { rows: 8 }, placeholder: "Provide a detailed description of the problem, including steps to reproduce." }
      - { label: "Attachments", name: attachments, model: attachments, type: attachmentupload, param: { uploadUrl: "/api/upload/ticket-attachments" } }
      - { label: "Customer Signature", name: customerSignature, model: customerSignature, type: signature-modal, param: { uploadUrl: "/api/upload/signatures", modalTitle: "Confirm with Signature" } }

  - label: "Location & Area"
    name: locationSection
    type: div
    class: "grid grid-cols-1 lg:grid-cols-2 gap-6"
    children:
      - label: "Issue Location"
        name: issueLocation
        model: issueLocation
        type: location
        param: { mapHeight: '300px' }
      - label: "Affected Area"
        name: affectedArea
        model: affectedArea
        type: geofence
        param: { mapHeight: '300px', allowedShapes: ['polygon', 'circle'] }

  - label: "Related Tasks"
    name: relatedTasksSection
    type: card
    children:
      - label: "Sub-Tasks"
        name: relatedTasks
        model: relatedTasks
        type: array_object_manager
        param:
          title: "Manage Sub-Tasks"
          itemKey: "uid"
          newItemTemplate: { uid: "", title: "", completed: false }
          columns:
            - { key: "title", label: "Task Title" }
            - { key: "completed", label: "Completed", formatter: "formatBoolean" }

#-------------------------------------------------------------------------------
# DATA VIEW DEFINITION (for View.vue)
#-------------------------------------------------------------------------------
view:
  - label: "Ticket Overview"
    name: ticketOverview
    type: card-stacked
    children:
      - { label: "Subject", model: subject, class: "text-lg font-semibold" }
      - { label: "Status", model: status, type: statusBadge }
      - { label: "Priority", model: priority, type: badge, param: { variant: "outline" } }
      - { label: "Agent", model: assignedAgent.name } # Example of nested data
      - { label: "Reported At", model: reportedAt, type: datetime }
      - { label: "Deadline", model: deadline, type: date }
      - { label: "Resolved", model: isResolved, type: booleanIcon }

  - label: "Full Description"
    name: descriptionView
    type: card
    children:
      - { label: "", model: content, type: markdown }

  - label: "Visual Information"
    name: visualInfo
    type: div
    class: "grid grid-cols-1 lg:grid-cols-2 gap-6"
    children:
      - label: "Issue Location"
        name: issueLocationView
        type: map-point
        model: issueLocation
        param: { mapHeight: "300px" }
      - label: "Affected Area"
        name: affectedAreaView
        type: map-geofence
        model: affectedArea
        param: { mapHeight: "300px", fitBounds: true }

  - label: "Attachments & Signature"
    name: attachmentsView
    type: card-stacked
    children:
      - { label: "Attachments", model: attachments, type: attachmentlist }
      - { label: "Customer Signature", model: customerSignature, type: image, param: { imageClass: "h-24 w-auto border p-2 bg-white rounded" } }

  - label: "Analytics (Chart)"
    name: analyticsView
    type: chart
    model: analyticsData
    param:
      chartType: bar
      xAxis: { dataKey: "day" }
      series:
        - { dataKey: "interactions", name: "Agent Interactions" }
      yAxis: { label: "Count" }

2. The Artisan Command to Run Open your terminal in the root of your Laravel project and run the single make:module-crud command:

php artisan make:module-crud crud_definitions/support_ticket_module.yml --single-yml

crud_definitions/support_ticket_module.yml: The path to the file you just created.
--single-yml: This is the crucial flag that tells the command to look for form:, view:, table:, etc., inside this one file.

3. Expected Output After running the command, you will see output from the orchestrator and each of its sub-commands. The following file structure will be created/updated:

your-laravel-project/
├── app/
│   ├── Http/
│   │   └── Controllers/
│   │       └── Support/
│   │           └── TicketController.php  <-- From make:inertia-crud
│   └── Models/
│       └── Support/
│           └── Ticket.php            <-- From make:inertia-crud
├── resources/
│   └── js/
│       └── Pages/
│           └── Support/
│               └── Ticket/
│                   ├── Index.vue         <-- From make:inertia-crud
│                   ├── Create.vue        <-- From make:vue-form
│                   ├── Edit.vue          <-- From make:vue-form
│                   ├── View.vue          <-- From make:vue-dataview
│                   ├── components/
│                   │   ├── forms/
│                   │   │   └── TicketForm.vue <-- From make:vue-form
│                   │   └── views/
│                   │       └── TicketDetailView.vue <-- From make:vue-dataview
│                   └── data/
│                       ├── columns.ts      <-- From make:table-columns
│                       └── schema.ts       <-- From make:zod-schema

4. Post-Generation Steps (Developer’s TODO List)

Define Routes: Open routes/web.php and add the resourceful route:

use App\Http\Controllers\Support\TicketController;

// ...
Route::resource('support/tickets', TicketController::class)->names('support.tickets');
// Add any custom action routes, e.g., for modals

Run Migrations: Create a migration for your tickets table/collection that includes all the fields defined in the schema_fields section.
Implement Controller Logic:

Open app/Http/Controllers/Support/TicketController.php.
Fill in the $validator_create and $validator_update arrays with proper Laravel validation rules (the generator makes a guess, but you should refine it).
In the additionalQuery method, add any necessary Eloquent with() clauses to eager-load relationships (e.g., ->with('assignedAgent')).
In index(), view(), edit(), pass any necessary extra data to the Inertia pages (e.g., a list of agents for a select dropdown).
Implement the actual database saving logic in store() and update() if you override them from the AdminController base.

Implement Page Logic:

Open resources/js/Pages/Support/Ticket/Create.vue and Edit.vue.
Inside the <TicketForm> component slot, implement the UI for the array_object_manager (#form_relatedTasks).
Provide the formatters object for the ArrayObjectManager via the form props if needed.
Open resources/js/Pages/Support/Ticket/View.vue.
Provide the formatters object with functions for statusBadge, booleanIcon, markdown, starRating, attachmentList etc., to be passed to <TicketDetailView>.
Implement handlers for @onPointClick and @map_viewport_change if you plan to use them.

Create Helper Files:

Ensure your resources/js/utils/formatters.ts file exists and contains the formatter functions (statusBadge, booleanIcon, etc.) referenced in your YAML.

This example provides a concrete workflow, from a single comprehensive YAML file to a nearly complete, functional CRUD module, showcasing the power and efficiency of the generator system you’ve built.

Developer Guide

Installation

Performance

Framework

Messaging Sub System

Document Process Sub System

ETL Sub System

Use Case

Batch Processing

Converter

Utility

Importer

Commands

Commands ( v2 )

MVC ( v2 )

Laravel

Comprehensive Usage Example: Building a “Support Ticket” Module

​Comprehensive Usage Example: Building a “Support Ticket” Module

Comprehensive Usage Example: Building a “Support Ticket” Module