Backend: Command-Line Interface (CLI)

Relevant source files

The following files were used as context for generating this wiki page:

• app/Console/Commands/CreateStores.php
• app/Console/Commands/FetchAll.php
• app/Console/Commands/InitDatabase.php
• app/Console/Kernel.php
• docker/php/schedule-cron
• docker/php/start-app.sh
• routes/console.php
• app/Console/Commands/RegeneratePriceCache.php

The PriceBuddy application utilizes Laravel's Artisan command-line interface to handle a variety of backend tasks, including application initialization, database management, and recurring data processing jobs. These commands are essential for both the initial setup of the application, particularly in a Docker environment, and for its ongoing maintenance, such as fetching daily product price updates.

The CLI is composed of several custom commands, prefixed with buddy:, which encapsulate specific business logic. These commands can be executed manually or automatically via scheduled tasks (cron) and application startup scripts.

Available Commands

The core functionality of the CLI is provided by a set of custom Artisan commands.

Command Signature	Description	Class File
buddy:init-db	Initialise the database with stores and run migrations.	app/Console/Commands/InitDatabase.php
buddy:create-stores	Create the default stores from a seeder file.	app/Console/Commands/CreateStores.php
buddy:fetch-all	Fetches prices for all products by dispatching jobs.	app/Console/Commands/FetchAll.php
buddy:regenerate-price-cache	Regenerate the price cache for all products.	app/Console/Commands/RegeneratePriceCache.php

Sources: app/Console/Commands/InitDatabase.php:14, app/Console/Commands/CreateStores.php:14, app/Console/Commands/FetchAll.php:14, app/Console/Commands/RegeneratePriceCache.php:14

Command Details

Database and Store Initialization

These commands are primarily used during the initial setup of the application.

buddy:init-db

This command orchestrates the entire database setup process. It ensures migrations are run and default data is seeded.

The execution flow of the buddy:init-db command is as follows:

• If the --fresh option is provided, it completely wipes and re-migrates the database, including running seeders.
• Otherwise, it runs any pending migrations.
• It then calls the buddy:create-stores command to populate the stores table.
• Finally, it caches Filament components.

Sources: app/Console/Commands/InitDatabase.php:24-40

buddy:create-stores

This command seeds the database with a predefined list of stores from database/seeders/stores.json.

• Signature: buddy:create-stores
• Logic:
  1. It first checks if any stores already exist in the database. If they do, the command exits to prevent duplication.
  2. The --force option can be used to bypass this check and run the seeder anyway.
  3. It reads the stores.json file.
  4. It iterates through the store data in the JSON file and creates new App\Models\Store records.

Sources: app/Console/Commands/CreateStores.php:24-42

Data Processing Commands

These commands handle the core data processing and maintenance tasks of the application.

buddy:fetch-all

This is a crucial command for the application's main function: keeping product prices updated.

• Signature: buddy:fetch-all
• Description: "Fetches prices for all products"
• Logic:
  1. Retrieves all Product models from the database.
  2. Iterates through each product.
  3. For each product, it dispatches a FetchProductPrice job to the queue. This allows for asynchronous and parallel processing of price fetching.
  4. A progress bar is displayed in the console to show the progress of dispatching jobs.

The following diagram illustrates the process when buddy:fetch-all is executed.

buddy:regenerate-price-cache

This command is used to rebuild the historical price cache for all products. This is useful for populating charts after an import or data change.

• Signature: buddy:regenerate-price-cache
• Description: "Regenerate the price cache for all products"
• Logic:
  1. Retrieves all Product models.
  2. For each product, it dispatches a RegeneratePriceCacheJob to the queue.

Sources: app/Console/Commands/RegeneratePriceCache.php:23-31

Execution and Scheduling

The CLI commands are executed in two primary ways: during the application startup sequence in the Docker container and via a scheduled cron job for recurring tasks.

Application Startup Sequence

The docker/php/start-app.sh script runs a series of commands to prepare the application when the container starts. This includes several Artisan commands.

This startup process ensures the database is ready and the application caches are primed before it begins serving requests.

Sources: docker/php/start-app.sh:4-29

Scheduled Tasks (Cron)

The application uses a standard cron job to trigger Laravel's command scheduler, which in turn executes specific Artisan commands at defined intervals.

1. System Cron: The docker/php/schedule-cron file sets up a system-level cron job that runs every minute. This job executes php artisan schedule:run.

   * * * * * cd /app && php artisan schedule:run >> /var/log/cron.log 2>&1
   

   Sources: docker/php/schedule-cron:1

2. Laravel Task Scheduler: The app/Console/Kernel.php file defines which commands the scheduler should run and when. The buddy:fetch-all command is scheduled to run daily.

   // app/Console/Kernel.php:25
   protected function schedule(Schedule $schedule): void
   {
       $schedule->command('buddy:fetch-all')->daily();
       // ...
   }
   

   Sources: app/Console/Kernel.php:25-27

This setup ensures that product prices are automatically updated every day without manual intervention.