Applink Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle via Composer:

   composer require bprs/applink-bundle
   

   Register the bundle in config/app.php under extra.bundles:

   Bprs\AppLinkBundle\AppLinkBundle::class => ['all' => true],
   

2. Configuration Publish the default config:

   php artisan vendor:publish --provider="Bprs\AppLinkBundle\AppLinkBundle" --tag="config"
   

   Update config/applink.php with your app’s deep-linking scheme (e.g., myapp://).

3. First Use Case Generate a deep link in a controller or Blade template:

   use Bprs\AppLinkBundle\Generator\DeepLinkGenerator;
   
   $generator = new DeepLinkGenerator();
   $deepLink = $generator->generate('user/profile', ['id' => 123]);
   // Output: "myapp://user/profile?id=123"
   

Implementation Patterns

Core Workflows

1. Generating Links Use the DeepLinkGenerator to create platform-specific links (iOS/Android):

   $generator = app(DeepLinkGenerator::class);
   $link = $generator->generate('checkout', ['cart_id' => 'abc123']);
   

2. Handling Incoming Links Register a route to capture deep links (e.g., app/handle-deep-link):

   Route::get('/handle-deep-link', [AppLinkController::class, 'handle']);
   

   Parse incoming links in the controller:

   use Bprs\AppLinkBundle\Parser\DeepLinkParser;
   
   $parser = new DeepLinkParser();
   $params = $parser->parse($request->getUri());
   // $params = ['route' => 'user/profile', 'id' => 123]
   

3. Blade Integration Create a custom Blade directive for convenience:

   Blade::directive('applink', function ($route) {
       return "<?php echo app(\\Bprs\\AppLinkBundle\\Generator\\DeepLinkGenerator::class)->generate({$route}); ?>";
   });
   

   Usage in Blade:

   <a href="{{ applink('product/view', ['id' => $product->id]) }}">View in App</a>
   

Advanced Patterns

• Dynamic Schemes: Override the default scheme per environment:

  $generator->setScheme(config('applink.scheme.staging'));
  

• Fallback URLs: Configure a web fallback for unsupported devices:

  $generator->setFallbackUrl('https://web.example.com');
  

• Analytics: Log deep link usage via middleware:

  public function handle($request, Closure $next) {
      if ($request->hasDeepLink()) {
          event(new DeepLinkOpened($request->getDeepLink()));
      }
      return $next($request);
  }
  

Gotchas and Tips

Common Pitfalls

1. Scheme Validation

   • Ensure the scheme (e.g., myapp://) matches the app’s Info.plist (iOS) or AndroidManifest.xml (Android).
   • Test with x-callback-url for iOS 9+ compatibility:

     $generator->setScheme('x-callback-url://myapp');
     

2. Query Parameter Escaping

   • URLs with special characters (e.g., ?name=John%20Doe) may break parsing. Use rawurlencode:

     $params = ['name' => rawurlencode('John Doe')];
     

3. Route Mismatches

   • If parsing fails, verify the route pattern in config/applink.php matches the generated link’s path.

Debugging Tips

• Log Generated Links:

  $generator->setDebug(true); // Logs to storage/logs/applink.log
  

• Validate Incoming Links: Use php artisan applink:validate to test parsing logic with sample URLs.

Extension Points

1. Custom Parsers Extend DeepLinkParser to handle non-standard formats:

   class CustomParser extends DeepLinkParser {
       protected function parseCustomFormat(string $uri): array {
           // Custom logic
       }
   }
   

   Register via service provider:

   $this->app->bind(DeepLinkParser::class, CustomParser::class);
   

2. Middleware for Security Restrict deep link handling to authenticated users:

   public function handle($request, Closure $next) {
       if ($request->hasDeepLink() && !$request->user()) {
           abort(403);
       }
       return $next($request);
   }
   

3. Environment-Specific Config Use Laravel’s config caching to avoid runtime overrides:

   php artisan config:cache