GenerateIdeHelpers Command

The custom-field:ide artisan command generates IDE helper stubs for CustomFieldBuilder macros. This provides autocomplete and type hints for dynamically registered field types in your IDE, making development faster and more reliable.

Namespace

JobMetric\CustomField\Commands\GenerateIdeHelpers

Command Signature

php artisan custom-field:ide

Overview

Laravel Custom Field uses Laravel's Macroable trait to dynamically register field types. While this provides flexibility, IDEs cannot provide autocomplete for these dynamic methods. The custom-field:ide command solves this by generating a helper file that documents all registered field types, enabling full IDE support.

Basic Usage

Generate IDE Helpers

Simply run the command:

php artisan custom-field:ide

Output:

IDE helper generated: /path/to/project/_ide_helper_custom_field.php

Generated File Location

The helper file is generated at:

{project_root}/_ide_helper_custom_field.php

Generated File Structure

File Content

The generated file contains PHPDoc annotations for all registered field types:

<?php

namespace JobMetric\CustomField;

/**
 * This file is auto-generated by custom-field:ide
 * It provides dynamic method hints for IDEs.
 *
 * @method static \JobMetric\CustomField\CustomFields\Text\Text text()
 * @method static \JobMetric\CustomField\CustomFields\Number\Number number()
 * @method static \JobMetric\CustomField\CustomFields\Email\Email email()
 * @method static \JobMetric\CustomField\CustomFields\Select\Select select()
 * @method static \JobMetric\CustomField\CustomFields\Radio\Radio radio()
 * @method static \JobMetric\CustomField\CustomFields\Color\Color color()
 * @method static \App\CustomFields\ColorPicker\ColorPicker colorPicker()
 * @method static \App\CustomFields\RichTextEditor\RichTextEditor richTextEditor()
 */
class CustomFieldBuilder
{
    // This class is intentionally left empty. Its purpose is to provide IDE hints for dynamically registered macros.
}

Method Documentation

Each @method annotation follows this pattern:

@method static {FullyQualifiedClassName} {methodName}()

Components:

• static: Indicates a static method
• {FullyQualifiedClassName}: The fully qualified class name of the field
• {methodName}(): The camelCase method name (derived from field type)

Example:

@method static \JobMetric\CustomField\CustomFields\Text\Text text()

This means:

• Method: CustomFieldBuilder::text()
• Returns: JobMetric\CustomField\CustomFields\Text\Text

How It Works

Discovery Process

1. Registry Access: The command accesses CustomFieldRegistry to get all registered fields
2. Field Iteration: Iterates through all registered field instances
3. Type Extraction: Gets the field type using FieldContract::type()
4. Method Name Generation: Converts type to camelCase for method name
5. Class Name Resolution: Gets the fully qualified class name
6. Documentation Generation: Creates PHPDoc annotations

Method Name Conversion

Field types are converted to camelCase method names:

Type to Method:

• text → text()
• color-picker → colorPicker()
• rich-text-editor → richTextEditor()
• date_time_picker → dateTimePicker()

Conversion Logic:

$method = Str::camel($type);

Class Name Resolution

The command uses get_class() to get the fully qualified class name:

$fqcn = '\\' . ltrim(get_class($field), '\\');

Examples:

• JobMetric\CustomField\CustomFields\Text\Text
• App\CustomFields\ColorPicker\ColorPicker

Complete Examples

Example 1: Basic Usage

php artisan custom-field:ide

Generated File:

<?php

namespace JobMetric\CustomField;

/**
 * This file is auto-generated by custom-field:ide
 * It provides dynamic method hints for IDEs.
 *
 * @method static \JobMetric\CustomField\CustomFields\Text\Text text()
 * @method static \JobMetric\CustomField\CustomFields\Number\Number number()
 * @method static \JobMetric\CustomField\CustomFields\Email\Email email()
 * @method static \JobMetric\CustomField\CustomFields\Select\Select select()
 * @method static \JobMetric\CustomField\CustomFields\Radio\Radio radio()
 */
class CustomFieldBuilder
{
    // This class is intentionally left empty. Its purpose is to provide IDE hints for dynamically registered macros.
}

Example 2: With Custom Fields

After registering custom fields:

// In AppServiceProvider
$registry = app('CustomFieldRegistry');
$registry->register(new \App\CustomFields\ColorPicker);
$registry->register(new \App\CustomFields\RichTextEditor);

Run the command:

php artisan custom-field:ide

Generated File:

<?php

namespace JobMetric\CustomField;

/**
 * This file is auto-generated by custom-field:ide
 * It provides dynamic method hints for IDEs.
 *
 * @method static \JobMetric\CustomField\CustomFields\Text\Text text()
 * @method static \JobMetric\CustomField\CustomFields\Select\Select select()
 * @method static \App\CustomFields\ColorPicker\ColorPicker colorPicker()
 * @method static \App\CustomFields\RichTextEditor\RichTextEditor richTextEditor()
 */
class CustomFieldBuilder
{
    // This class is intentionally left empty. Its purpose is to provide IDE hints for dynamically registered macros.
}

IDE Support

PHPStorm / IntelliJ IDEA

PHPStorm automatically recognizes the generated helper file and provides:

• Autocomplete: Method suggestions when typing CustomFieldBuilder::
• Type Hints: Return type information for each method
• Go to Definition: Navigate to the actual field class
• Refactoring: Safe renaming and refactoring support

Usage:

use JobMetric\CustomField\CustomFieldBuilder;

// IDE will autocomplete: text(), select(), colorPicker(), etc.
$field = CustomFieldBuilder::text()
    ->name('email')
    ->build();

Visual Studio Code

With PHP Intelephense or PHP IntelliSense extensions:

• Autocomplete: Method suggestions
• Type Checking: Type validation
• Hover Information: Show method signatures

Other IDEs

Most modern PHP IDEs that support PHPDoc annotations will benefit from the generated helper file.

When to Regenerate

After Registering New Fields

Whenever you register a new custom field, regenerate the helpers:

// Register new field
$registry->register(new \App\CustomFields\MyNewField);

// Regenerate helpers
php artisan custom-field:ide

After Package Updates

If you update the laravel-custom-field package and new default fields are added:

composer update jobmetric/laravel-custom-field
php artisan custom-field:ide

In Development Workflow

Include in your development workflow:

# After creating a new field
php artisan custom-field:make MyField
php artisan custom-field:ide

# Or add to composer scripts
"post-autoload-dump": [
    "@php artisan custom-field:ide"
]

Integration with Composer

Automatic Generation

Add to your composer.json scripts:

{
    "scripts": {
        "post-autoload-dump": [
            "@php artisan custom-field:ide"
        ]
    }
}

This automatically regenerates helpers after:

• composer install
• composer update
• composer dump-autoload

Package Integration

The laravel-custom-field package includes this in its own scripts:

{
    "scripts": {
        "post-install-cmd": [
            "@php scripts/generate_ide_if_local.php"
        ],
        "post-update-cmd": [
            "@php scripts/generate_ide_if_local.php"
        ],
        "post-autoload-dump": [
            "@php scripts/generate_ide_if_local.php"
        ]
    }
}

File Management

Git Integration

Recommended: Add to .gitignore:

# IDE Helper files
_ide_helper_custom_field.php

Why?

• File is auto-generated
• Content varies by registered fields
• Can be regenerated anytime

Alternative: Commit the file if you want consistent IDE support across the team.

File Location

The file is generated at the project root:

{project_root}/
├── _ide_helper_custom_field.php
├── app/
├── config/
└── ...

Note: This location is hardcoded in the command. To change it, you would need to modify the command class.

Troubleshooting

IDE Not Recognizing Helpers

If your IDE doesn't provide autocomplete:

1. Check File Exists: Verify _ide_helper_custom_field.php exists
2. Regenerate: Run php artisan custom-field:ide again
3. IDE Cache: Clear IDE cache and restart
4. Namespace: Ensure the namespace matches JobMetric\CustomField
5. Composer Autoload: Run composer dump-autoload

Missing Custom Fields

If your custom fields don't appear in the generated file:

1. Check Registration: Ensure fields are registered before running the command
2. Service Provider Order: Ensure registration happens in boot() method
3. Run After Registration: Run the command after all fields are registered

Outdated Helpers

If helpers are outdated:

1. Regenerate: Run php artisan custom-field:ide
2. Check Registration: Verify all fields are registered
3. Clear Cache: Clear any IDE or application cache

Best Practices

1. Regenerate Regularly: Run after registering new fields
2. Automate: Add to composer scripts for automatic generation
3. Version Control: Consider adding to .gitignore if auto-generated
4. Document: Inform team members about the helper file
5. CI/CD: Include regeneration in your deployment process if needed

Advanced Usage

Custom Generation Script

Create a custom script for your workflow:

<?php

// scripts/generate-custom-field-helpers.php

require __DIR__.'/../vendor/autoload.php';

$app = require_once __DIR__.'/../bootstrap/app.php';
$app->make(\Illuminate\Contracts\Console\Kernel::class)->bootstrap();

Artisan::call('custom-field:ide');

echo "Custom field IDE helpers generated!\n";

Run with:

php scripts/generate-custom-field-helpers.php

Integration with Other IDE Helpers

If you use other IDE helper packages (like barryvdh/laravel-ide-helper), you can combine them:

{
    "scripts": {
        "post-autoload-dump": [
            "@php artisan ide-helper:generate",
            "@php artisan custom-field:ide"
        ]
    }
}

Related Documentation

• MakeCustomField Command
• CustomFieldRegistry
• CustomFieldBuilder
• CustomField