Ide Stubs Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer (if available) or manually include the stubs in your project:

   composer require phalcon/ide-stubs
   

   (Note: Since the package is for Phalcon, ensure your project uses Phalcon PHP framework.)

2. Enable Stubs Place the stubs in your IDE’s metadata directory (e.g., vendor/phalcon/ide-stubs/stubs for PHPStorm) or configure your IDE to use them:

   • PHPStorm: Go to File > Settings > Languages & Frameworks > PHP > Stub Files and add the stubs path.
   • VSCode: Use the php-stubs extension and point it to the stubs directory.

3. First Use Case Open a Phalcon model, service, or DI container class. Autocomplete, type hints, and method signatures should now appear without errors (e.g., Phalcon\Di\Injectable, Phalcon\Mvc\Model).

Implementation Patterns

Workflow Integration

1. Leveraging Autocomplete

   • Use stubs for Phalcon’s core classes (e.g., Phalcon\Mvc\Model, Phalcon\Di\FactoryDefault) to avoid manual @var annotations.
   • Example: Typing new \Phalcon\Mvc\Model\ triggers autocomplete for find(), create(), etc.

2. Dependency Injection (DI) Clarity

   • Stubbed Phalcon\Di\Injectable methods (e.g., get(), setService()) provide real-time hints for service binding.
   • Example:

     $this->di->get('modelsManager'); // Autocomplete shows available services.
     

3. Model and ORM Support

   • Stub Phalcon\Mvc\Model\Behavior and Phalcon\Mvc\Model\Relation for seamless ORM interactions.
   • Example: hasMany() or belongsTo() relations populate with correct parameters.

4. Configuration and Events

   • Stub Phalcon\Events\Manager and Phalcon\Config for event-driven workflows.
   • Example: Attaching listeners to Phalcon\Mvc\Application events.

5. Custom Stubs for Extensions

   • If using Phalcon extensions (e.g., phalcon/validation), generate or include their stubs alongside the core package.

Gotchas and Tips

Pitfalls

1. IDE-Specific Quirks

   • PHPStorm: Ensure stubs are marked as "Read-only" in Settings > Directories to avoid accidental overwrites.
   • VSCode: Cache issues may require restarting the IDE after adding stubs.

2. Stub Version Mismatch

   • Stubs for Phalcon v5.x won’t work with v4.x. Verify compatibility with your Phalcon version (check the stubs’ README or release notes).

3. Dynamic Properties

   • Phalcon’s magic methods (e.g., __get(), __set()) may not be fully stubbed. Use @property annotations for dynamic properties:

     /** @property string $nonExistentProperty */
     

4. Namespace Conflicts

   • Avoid naming custom classes Phalcon or Di to prevent IDE conflicts with stubbed namespaces.

Debugging Tips

1. Stub Validation

   • Test stubs with a minimal Phalcon project (e.g., phalcon/devtools skeleton). If autocompletion fails, the stubs may be incomplete.

2. Fallback to DocBlocks

   • For unsupported methods, add PHPDoc comments:

     /**
      * @method static \App\Models\User findFirst($parameters = null)
      */
     class User extends \Phalcon\Mvc\Model {}
     

3. Generating Custom Stubs

   • Use tools like phpDocumentor or phpstan/phpdoc-parser to generate stubs for custom Phalcon extensions.

Extension Points

1. Merge Stubs

   • Combine stubs from multiple sources (e.g., core + extensions) into a single directory for unified IDE support.

2. CI/CD Integration

   • Add a composer post-install script to symlink stubs to a project-wide stubs/ directory:

     {
       "scripts": {
         "post-install-cmd": [
           "php -r \"if (!file_exists('stubs')) symlink('vendor/phalcon/ide-stubs/stubs', 'stubs');\""
         ]
       }
     }
     

3. Community Contributions

   • Report missing stubs to the Phalcon GitHub repo or fork the project to extend stubs for unsupported classes.