Hosting Laravel Package

Getting Started

1. Installation:

   composer require becklyn/hosting
   

   Publish the default configuration:

   php artisan vendor:publish --provider="Becklyn\Hosting\HostingBundle" --tag="config"
   

   Update config/packages/hosting.yaml with your required values:

   becklyn_hosting:
       tier: "%env(APP_ENV)%"  # e.g., "production", "staging"
       project: "your_project_name"
       installation: "unique_installation_key"
       trackjs: "%env(TRACKJS_TOKEN)%"
   

2. First Use Case: Access the hosting config in a controller or service:

   use Becklyn\Hosting\Config\HostingConfig;
   
   public function __construct(private HostingConfig $hostingConfig) {}
   
   public function index()
   {
       $tier = $this->hostingConfig->getTier();
       $project = $this->hostingConfig->getProject();
       // Use $tier and $project as needed
   }
   

3. Embed Monitoring in Twig: Add the Twig function to your base template (if using Twig):

   {% block javascripts %}
       {{- hosting_embed_monitoring() -}}
       <!-- Other JS -->
   {% endblock %}
   

Implementation Patterns

Environment-Aware Logic

Use the HostingConfig service to dynamically adjust behavior:

if ($hostingConfig->isInDevelopmentTier()) {
    // Enable debug tools, disable caching, etc.
}

Uptime Monitoring Integration

Inject uptime monitor comments into HTML responses automatically. No manual changes needed—just ensure your templates render HTML (not binary responses like PDFs).

TrackJS Integration

Conditionally load TrackJS only in non-development tiers:

{% if not hostingConfig.isInDevelopmentTier() %}
    {{- hosting_embed_monitoring() -}}
{% endif %}

Asset Pipeline Integration

Leverage the @hosting namespace for hosting-specific assets (e.g., monitoring scripts):

// In your asset file (e.g., app.js)
import './hosting/monitoring.js';

Middleware for Dynamic Config

Create middleware to override config based on runtime conditions:

public function handle(Request $request, Closure $next)
{
    if ($request->ip() === '127.0.0.1') {
        $this->hostingConfig->setTier('local');
    }
    return $next($request);
}

Twig Extensions for Conditional Rendering

Use the hosting_tier Twig function to show/hide UI elements:

{% if hosting_tier() == 'production' %}
    <div class="production-only-feature">...</div>
{% endif %}

Gotchas and Tips

Configuration Pitfalls

1. Tier Validation: The bundle validates tier names (e.g., production, staging). Custom tiers must be explicitly allowed in the config:

   becklyn_hosting:
       allowed_tiers: ["production", "staging", "local"]
   

2. Installation Key Format: Ensure the installation key uses only a-z, 0-9, -, or _. Invalid keys will throw exceptions.

3. Environment Variables: Use %env() syntax for dynamic values (e.g., trackjs: "%env(TRACKJS_TOKEN)%"). Empty env vars may cause issues—validate them:

   if (empty($this->hostingConfig->getTrackjsToken())) {
       // Handle missing token
   }
   

Debugging Tips

1. Missing HTML Comments: If uptime monitor comments aren’t appearing, check:

   • The response is HTML (not JSON/XML/binary).
   • No middleware is stripping comments (e.g., minification tools).

2. TrackJS Not Loading: Verify:

   • The trackjs token is set in config.
   • The tier is not development (TrackJS is excluded by default).
   • No JavaScript errors block the script load.

3. Asset Namespace Issues: The @hosting namespace requires the Becklyn Assets Bundle. If missing, manually import assets or configure your asset pipeline.

Extension Points

1. Custom Monitoring Scripts: Override the Twig function hosting_embed_monitoring() by extending the bundle’s Twig extension:

   // src/Twig/Extension/HostingExtension.php
   public function hosting_embed_monitoring()
   {
       return $this->renderScript('your_custom_monitoring_script.js');
   }
   

2. Dynamic Tier Logic: Extend HostingConfig to add custom tier checks:

   public function isCanaryRelease()
   {
       return $this->getTier() === 'canary';
   }
   

3. Middleware for Advanced Use Cases: Create custom middleware to modify the HostingConfig dynamically:

   public function handle(Request $request, Closure $next)
   {
       $this->hostingConfig->setTier($request->header('X-Deployment-Tier'));
       return $next($request);
   }
   

Laravel-Specific Quirks

1. Twig Integration: If using Blade instead of Twig, replace hosting_embed_monitoring() with a Blade directive:

   // app/Providers/BladeServiceProvider.php
   Blade::directive('hostingMonitoring', function () {
       return "<?php echo \Becklyn\Hosting\Twig\HostingExtension::embedMonitoring(); ?>";
   });
   

   Usage:

   @hostingMonitoring
   

2. Service Container Conflicts: Avoid naming collisions with Laravel’s services. Prefix the HostingConfig binding:

   $this->app->bind('becklyn.hosting.config', function ($app) {
       return new HostingConfig($app['config']);
   });
   

3. Asset Pipeline: For Laravel Mix/Vite, manually define the @hosting namespace in your config:

   // mix.js
   mix.setPublicPath('public');
   mix.webpackConfig({
       resolve: {
           alias: {
               '@hosting': path.resolve(__dirname, 'resources/assets/hosting'),
           },
       },
   });
   

Performance Considerations

1. Avoid Overhead in Development: Disable TrackJS and uptime monitoring in development tier to reduce HTTP requests:

   becklyn_hosting:
       trackjs: null  # Disable in development
   

2. Cache Hosting Config: Laravel’s config caching will automatically optimize repeated HostingConfig calls. No additional steps needed.