Flysystem

Overview Modern Laravel development moves at a breakneck pace, and staying ahead of the curve requires more than just reading the documentation. It involves understanding the interplay between monitoring tools, cloud infrastructure, and the core framework features that streamline developer workflows. This tutorial explores the critical implementations discussed during the latest office hours, focusing on Laravel Nightwatch sampling techniques, efficient file handling on Laravel Cloud using Cloudflare R2, and leveraging Laravel Cashier for robust payment integration. Effective monitoring isn't just about catching every single error; it's about smart data collection that maintains application performance and controls costs. Likewise, moving from traditional VPS hosting to modern cloud solutions like Laravel Cloud necessitates a shift in how we handle persistent data. By breaking down these concepts into actionable patterns, we can build more resilient, scalable applications while taking full advantage of the first-party ecosystem. Prerequisites To get the most out of this guide, you should be comfortable with the following: * **PHP 8.2+**: Familiarity with modern PHP syntax and attributes. * **Laravel Fundamentals**: A solid understanding of the Service Container, Facades, and the Eloquent ORM. * **Cloud Infrastructure**: Basic knowledge of AWS S3 or S3-compatible storage logic. * **CLI Proficiency**: Comfort running `artisan` commands and managing composer packages. Key Libraries & Tools * **Laravel Nightwatch**: A first-party monitoring and observability tool designed specifically for the Laravel ecosystem. * **Laravel Cloud**: A serverless deployment platform that integrates deeply with Laravel's core services. * **Cloudflare R2**: S3-compatible object storage used by Laravel Cloud for persistent file storage. * **Laravel Cashier**: An expressive, fluent interface to Stripe's subscription billing services. * **Inertia.js**: A tool for building single-page apps using classic server-side routing and controllers. Fine-Grained Monitoring with Nightwatch Sampling Monitoring high-traffic applications can quickly lead to an overwhelming volume of data and inflated costs. Laravel Nightwatch solves this through **sampling**. Instead of capturing every single request, you can instruct the agent to capture a representative percentage of traffic while still prioritizing critical events like exceptions. Implementation: Dynamic and Route-Based Sampling While global sampling is configured via environment variables, the new `Sample` facade allows for granular control within your application logic. This is particularly useful for excluding health check routes or heavily sampling resource-intensive API endpoints. ```python Note: While the logic is PHP, we follow the Markdown tag requirement using the Sample facade for route-specific logic use Laravel\Nightwatch\Facades\Sample; Dynamic sampling within a controller or middleware Sample::rate(0.1); # Only sample 10% of executions for this specific logic path ``` When using route-based sampling, you can define fallback behaviors for unmatched routes. This ensures that your most important business logic is always monitored, while high-volume, low-priority routes don't exhaust your event quota. A common pattern is to set a global sample rate of 10% but override it to 100% for critical checkout or authentication routes. Persistent Storage on Laravel Cloud with R2 Laravel Cloud infrastructure is ephemeral. Any files written directly to the server's local disk will vanish upon the next deployment or scale event. To handle persistent file uploads, you must use **Buckets**, which are powered by Cloudflare R2. The Flysystem Bridge Because Cloudflare R2 is S3-compatible, you don't need a custom driver; however, you **must** install the AWS S3 adapter for Flysystem. ```bash composer require league/flysystem-aws-s3-v3 "^3.0" ``` Once installed, Laravel Cloud automatically injects the necessary environment variables when you attach a bucket to your project. You should always interact with these buckets via the `Storage` facade to maintain environment portability. ```python Storing a file on the default Cloud bucket use Illuminate\Support\Facades\Storage; This uses the R2 bucket configured as your default disk Storage::put('avatars/1', $fileContents); For private buckets, generate a temporary URL for secure access $url = Storage::temporaryUrl( 'documents/contract.pdf', now()->addMinutes(15) ); ``` Public vs. Private Buckets Choosing the right bucket type is essential for security. **Public buckets** are ideal for assets like profile pictures that should be accessible via a direct URL. **Private buckets** should be used for sensitive user data, where files are only accessible via signed temporary URLs generated by your application backend. Simplifying Payments with Laravel Cashier Handling payments manually involves managing complex webhooks, subscription states, and Stripe API versioning. Laravel Cashier abstracts this complexity into a fluent syntax that feels native to Laravel. Instead of writing custom logic to track if a user is subscribed, Laravel Cashier provides a `Billable` trait that adds methods directly to your User model. This allows you to perform checks like `$user->subscribed('main')` throughout your application. Implementation: The Checkout Flow A modern best practice is using **Stripe Checkout**, which offloads the UI and PCI compliance to Stripe while Laravel Cashier handles the backend synchronization. ```python Redirecting to a Stripe-hosted checkout page return $request->user() ->newSubscription('default', 'price_premium_monthly') ->checkout([ 'success_url' => route('dashboard'), 'cancel_url' => route('subscribe'), ]); ``` This approach drastically reduces the surface area for bugs and ensures that your payment logic remains clean and maintainable. Syntax Notes & Conventions * **Facade usage**: This guide emphasizes using Facades like `Storage` and `Sample`. While dependency injection is often preferred in large-scale testing, Facades remain the standard for Laravel's fluent, expressive syntax in tutorials. * **The 'Default' Pattern**: Always configure a default disk in `filesystems.php`. This allows your code to remain `Storage::put()` rather than `Storage::disk('s3')->put()`, making local development on the `local` disk seamless compared to production on Cloudflare R2. * **Trait-based functionality**: Laravel heavily uses traits (like `Billable`) to augment models. Ensure you import the correct namespace to avoid "method not found" errors. Practical Examples * **E-commerce Image Processing**: Use a Laravel queue to process product images uploaded to a private R2 bucket, then move the optimized versions to a public bucket for CDN delivery. * **SaaS Usage Monitoring**: Implement Laravel Nightwatch dynamic sampling to monitor 100% of traffic for a "Beta" group of users while sampling 5% of the general population to save on event costs. * **Subscription Paywalls**: Use Laravel Cashier middleware to automatically redirect non-paying users away from premium Inertia.js routes. Tips & Gotchas * **The S3 Adapter Trap**: One of the most common issues when deploying to Laravel Cloud is forgetting the `league/flysystem-aws-s3-v3` package. Without it, the `s3` driver (used for R2) simply won't initialize. * **Sampling Exceptions**: Be careful with sampling. While you might sample requests at 10%, you usually want to sample **exceptions** at 100% to ensure you don't miss any critical bugs. Laravel Nightwatch allows you to configure these separately. * **DNS Propagation**: When setting up custom domains on Laravel Cloud, propagation can take anywhere from minutes to 24 hours. If a domain is stuck in "Pending" for more than a day, it's usually a sign of a DNS record mismatch. * **Eloquent & Composite Keys**: Laravel does not have first-party support for composite primary keys. If you are migrating a legacy database that uses them, you will need to use a community package or define a surrogate `id` column to keep Eloquent ORM happy.