Laravelscandocument Laravel Package

Getting Started

1. Install via Composer and let Laravel auto-discover the service provider:

   composer require webmavens/laravelscandocument
   

2. Publish any package assets/config. Check the repo README for the exact tag; typical patterns are:

   php artisan vendor:publish --provider="Webmavens\LaravelScanDocument\ScanDocumentServiceProvider"
   

   Then inspect config/scandocument.php (or the equivalent) for disk, driver, DPI, and temp-path settings.

3. Where to look first: open src/ and locate the service provider and the main facade/class. Because the package has very low adoption (3 stars, 0 dependents), do not assume the README is complete — read the source to confirm method signatures before wiring it into a controller.

4. First use case: accept a user-uploaded image or PDF, pass it through the package to produce a normalized/scanned output, and persist the result:

   use Illuminate\Support\Facades\Storage;
   use Webmavens\LaravelScanDocument\Facades\ScanDocument; // confirm actual namespace
   
   $path = $request->file('document')->store('incoming', 'local');
   
   $scanned = ScanDocument::scan(Storage::disk('local')->path($path));
   
   Storage::disk('local')->put('scans/result.pdf', $scanned);
   

   Treat the class/facade name and method names as illustrative — verify them against the installed version.

Implementation Patterns

Wrap the package behind your own service. Because the package is small and lightly maintained, avoid calling it directly from controllers. Create an application-level DocumentScanner class that depends on the package and exposes the two or three operations you actually need (scan(), toPdf(), getPreview()). When the package is abandoned or replaced, you change one file.

namespace App\Services;

class DocumentScanner
{
    public function __construct(private $scanner) {}

    public function scanToDisk(string $inputPath, string $disk, string $outputPath): string
    {
        $result = $this->scanner->scan($inputPath);
        \Storage::disk($disk)->put($outputPath, $result);
        return $outputPath;
    }
}

Bind it in a service provider and inject the interface into controllers and jobs.

Validate before scanning. Scanning is expensive; reject unsupported MIME types and oversized files at the Form Request layer:

$request->validate([
    'document' => ['required', 'file', 'mimes:jpg,jpeg,png,pdf', 'max:10240'],
]);

Queue heavy work. Scans are CPU- and memory-bound. Dispatch a job, return a scan ID/token, and poll or broadcast when the output is ready:

dispatch(new ProcessScan($uploadId))->onQueue('documents');

Store the input on a private disk first so the job can retry without re-uploading.

Stream results to the user. For downloads, return a response with a proper filename rather than dumping bytes:

return response()->download(
    Storage::disk('local')->path($outputPath),
    "scan-{$id}.pdf",
    ['Content-Type' => 'application/pdf']
);

Configuration over hardcoding. Read disk, output format, DPI, and temp directory from config('scandocument.*') so staging and production can differ. If the config file lacks keys you need, add them in a published copy.

Testing. Fake the disk and assert the file exists; stub the scanner in your service tests:

Storage::fake('local');
// ...
Storage::disk('local')->assertExists('scans/result.pdf');

Gotchas and Tips

• Verify the actual API first. With 3 stars and 0 dependents there is little community evidence of correct usage. Read src/, composer.json, and any tests in the repo before trusting examples in the README. Method names may differ from what you'd expect.
• Pin the version. composer require webmavens/laravelscandocument:^x.y rather than a floating constraint; a small package is more likely to introduce breaking changes in patch releases. Commit the lockfile.
• Check native dependencies. Document scanning typically needs GD, Imagick, or a CLI tool (Ghostscript, ImageMagick) on the server. Docker images often omit these; test on a container matching production early.
• Mind memory and time limits. Large PDFs and high-DPI scans blow past PHP's default memory_limit and max_execution_time. Set ini_set or php artisan queue:work --timeout per job, not globally.
• Clean up temp files. The package will likely write intermediates to storage/app or sys_get_temp_dir(). Add a scheduled command to purge orphans, or the disk fills silently.
• Config cache is deceptive. After php artisan config:cache, changes to config/scandocument.php won't take effect until you clear it. This is the number-one source of "it worked locally" bugs with packages like this.
• Facade aliasing / namespace collisions. If another package ships a ScanDocument facade, alias yours explicitly in config/app.php or reference the fully-qualified class.
• Extension points are limited. Expect to extend via the container (bind your own implementation behind the package's interface) or by forking the repo. Because it's MIT-licensed, forking and vendoring is a reasonable contingency plan if the package stalls.
• Watch for abandoned maintenance. Check the last commit date versus the release date, and set a reminder to re-evaluate. If the package stops receiving updates, your wrapper service makes the migration to spatie/pdf-to-image, imagick, or an external OCR service straightforward.