Pengublade Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require realzone22/pengublade
   

   Publish the package assets (if needed) via:

   php artisan vendor:publish --provider="RealZone22\PenguBlade\PenguBladeServiceProvider" --tag="pengublade-views"
   

2. First Use Case: Use a pre-built component in a Blade view:

   @penguButton('Click Me', 'primary')
   

   Verify the component renders as expected in your Laravel app.

Where to Look First

• Documentation: Start with the wiki for component reference and usage examples.
• Published Views: Check resources/views/vendor/pengublade/ for default templates (if published).
• Service Provider: Review PenguBladeServiceProvider for registration logic and customization hooks.

Implementation Patterns

Common Workflows

1. Component Integration:

   • Replace vanilla Blade with PenguBlade components for consistent UI (e.g., @penguCard, @penguAlert).
   • Example: Replace a form with @penguForm for built-in validation styling:

     @penguForm('user', route('users.store'))
         @penguInput('name', 'text', 'Name')
         @penguButton('Submit', 'success')
     @endpenguForm
     

2. Dynamic Styling:

   • Pass dynamic classes/props to components:

     @penguButton('Save', 'primary', ['disabled' => $isLoading])
     

3. Layout Consistency:

   • Use @penguLayout for responsive grids or @penguContainer for padding/margins:

     @penguLayout
         @penguContainer
             <!-- Content -->
         @endpenguContainer
     @endpenguLayout
     

4. Customization:

   • Override default templates by creating mirrored paths in resources/views/vendor/pengublade/.
   • Extend components via traits or mixins (if supported).

Integration Tips

• Tailwind/Other CSS: Ensure PenguBlade’s CSS (if bundled) doesn’t conflict with your existing setup. Disable defaults if needed:

  // config/pengublade.php
  'use_default_css' => false,
  

• Localization: Pass language-specific props to components (e.g., @penguButton('Guardar', 'primary', ['lang' => 'es'])).
• Testing: Mock components in PHPUnit using Blade’s Blade::render() or Laravel’s View facade.

Gotchas and Tips

Pitfalls

1. Component Registration:

   • If components don’t render, verify the service provider is registered in config/app.php under providers.
   • Check for typos in component names (e.g., @penguButton vs @pengu-btn).

2. CSS/JS Dependencies:

   • Some components may require Penguin UI’s core CSS/JS. Include them in your layout:

     <link href="{{ asset('vendor/pengu-ui/css/pengu.min.css') }}" rel="stylesheet">
     

3. Blade Cache:

   • Clear Blade cache after publishing views:

     php artisan view:clear
     

4. Dynamic Props:

   • Avoid passing invalid HTML attributes (e.g., data-* props may need escaping). Use htmlspecialchars or e() in Blade.

Debugging

• Inspect Output: Use browser dev tools to check if components render raw Blade syntax (indicates registration failure).
• Log Component Calls: Temporarily add {{ dd(__FILE__, __LINE__) }} inside components to trace execution.
• Check for Errors: Enable Laravel’s debug mode (APP_DEBUG=true) and inspect logs (storage/logs/laravel.log).

Extension Points

1. Custom Components:

   • Create new components by extending RealZone22\PenguBlade\Components\Component and register them in the service provider:

     $this->app->make('view')->addNamespace('pengu', resource_path('views/vendor/pengublade/custom'));
     

2. Configuration:

   • Override defaults in config/pengublade.php (e.g., button sizes, colors):

     'button_sizes' => ['sm', 'md', 'lg'],
     'default_size' => 'md',
     

3. Theming:

   • Use CSS variables or SASS to theme components globally without modifying source files.

Pro Tips

• Partial Renders: Use @penguSlot for reusable content blocks within components.
• Performance: Lazy-load non-critical components via JavaScript if they’re heavy.
• Community: Engage with the maintainer via GitHub Discussions for unsupported features or edge cases.