Corelibrary Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer:

   composer require coresys/corelibrary
   

   Publish the config (if available):

   php artisan vendor:publish --provider="CoreSys\Corelibrary\CorelibraryServiceProvider"
   

2. First Use Case

   • Core Utility Functions: Check the CoreSys\Corelibrary\Support\Helpers namespace for static utility methods (e.g., string manipulation, array helpers).
   • Service Container Bindings: Verify if the package registers any Laravel services (e.g., CoreSys\Corelibrary\Services\*) via app() or resolve().
   • Facade Usage: If a facade exists (e.g., CoreSys), test basic functionality:

     use CoreSys\Facades\CoreSys;
     CoreSys::someMethod(); // Replace with actual method
     

3. Documentation

   • Since the package lacks stars/dependents, refer to:
     • README.md in the repo (if present).
     • Class docblocks (e.g., phpdoc for CoreSys\Corelibrary\*).
     • Bitbucket wiki (if available).

Implementation Patterns

Common Workflows

1. Utility Helpers

   • Replace manual string/array operations with package methods:

     use CoreSys\Corelibrary\Support\Helpers\StringHelper;
     $snakeCase = StringHelper::toSnakeCase('CamelCaseString');
     

   • Pattern: Prefix helper calls with Helpers\ for clarity.

2. Service Integration

   • If the package provides services (e.g., logging, caching wrappers), bind them in AppServiceProvider:

     $this->app->bind('customLogger', function () {
         return new \CoreSys\Corelibrary\Services\LoggerService();
     });
     

   • Pattern: Use dependency injection for testability.

3. Event Listeners/Observers

   • If the package emits events (e.g., CoreSys\Events\*), listen in EventServiceProvider:

     protected $listen = [
         'CoreSys\Events\DataProcessed' => [
             'App\Listeners\HandleDataProcessed',
         ],
     ];
     

4. Middleware

   • Extend package middleware (if available) by creating custom middleware that wraps it:

     namespace App\Http\Middleware;
     use CoreSys\Corelibrary\Http\Middleware\AuthenticateAsCoreSys;
     
     class CustomAuth extends AuthenticateAsCoreSys {
         public function handle($request, Closure $next) {
             // Pre/post-processing
             return parent::handle($request, $next);
         }
     }
     

5. Configuration

   • Override default settings in config/corelibrary.php:

     'default_locale' => 'en_US',
     'api_timeout' => 30,
     

Integration Tips

• Laravel Mix/Webpack: If the package includes assets (e.g., JS/CSS), compile them into your build:

  // webpack.mix.js
  mix.js('resources/js/corelibrary.js', 'public/js')
       .styles('resources/css/corelibrary.css', 'public/css');
  

• Testing: Mock package services in PHPUnit:

  $this->app->instance('CoreSys\Corelibrary\Services\SomeService', Mockery::mock());
  

Gotchas and Tips

Pitfalls

1. Undocumented Features

   • Issue: Methods/events may lack documentation.
   • Fix: Use php artisan tinker to explore:

     php artisan tinker
     >>> \CoreSys\Corelibrary\Support\Helpers::classMethods()
     

2. Namespace Conflicts

   • Issue: The package might use CoreSys namespace, which could clash with other vendors.
   • Fix: Alias classes in composer.json:

     "autoload": {
         "psr-4": {
             "App\\": "app/",
             "CoreSys\\": "vendor/coresys/corelibrary/src/"
         }
     }
     

3. Configuration Overrides

   • Issue: Published config may not merge properly.
   • Fix: Use array_merge in config/corelibrary.php:

     return array_merge(
         require __DIR__.'/corelibrary.php',
         $this->getCustomConfig()
     );
     

4. Service Provider Loading

   • Issue: Package may not auto-register if Laravel’s service provider order is incorrect.
   • Fix: Ensure CorelibraryServiceProvider loads after AppServiceProvider in config/app.php.

5. Deprecated Methods

   • Issue: Older versions may use deprecated Laravel features (e.g., Route::bind()).
   • Fix: Check composer.json for Laravel version constraints and update accordingly.

Debugging Tips

• Log Output: Use the package’s logger (if available) or Laravel’s:

  \Log::debug('Corelibrary debug', ['data' => $variable]);
  

• Xdebug: Step through package code by adding breakpoints in vendor/coresys/corelibrary/src/.
• Error Handling: Wrap package calls in try-catch:

  try {
      CoreSys::riskyOperation();
  } catch (\CoreSys\Corelibrary\Exceptions\CorelibraryException $e) {
      \Log::error($e->getMessage());
  }
  

Extension Points

1. Custom Helpers

   • Extend existing helpers by creating a trait:

     namespace App\Support;
     use CoreSys\Corelibrary\Support\Helpers\StringHelper;
     
     trait ExtendedStringHelper {
         public static function customMethod($input) {
             return StringHelper::toSnakeCase($input) . '_extended';
         }
     }
     

2. Service Decorators

   • Decorate package services for additional logic:

     class DecoratedLogger implements \Psr\Log\LoggerInterface {
         protected $logger;
         public function __construct(\CoreSys\Corelibrary\Services\LoggerService $logger) {
             $this->logger = $logger;
         }
         public function log($level, $message) {
             // Add custom logic
             $this->logger->log($level, $message);
         }
     }
     

3. Event Subscribers

   • Subscribe to package events in EventServiceProvider:

     protected $subscribe = [
         \CoreSys\Corelibrary\Events\DataProcessed::class => [
             \App\Listeners\CustomDataListener::class,
         ],
     ];
     

4. Blade Directives

   • If the package includes Blade helpers, extend them:

     Blade::directive('corelibrary', function ($expression) {
         return "<?php echo CoreSys::render{$expression}(); ?>";
     });