Project Configuration

Relevant source files

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

• app/Settings/AppSettings.php
• app/Filament/Pages/AppSettingsPage.php
• config/app.php
• docker/php/start-app.sh
• README.md
• phpunit.xml
• composer.json

The PriceBuddy application utilizes a multi-layered configuration system. Core application settings are managed through environment variables in the .env file. More specific, user-adjustable settings are handled via a dedicated settings page in the application's admin panel, which leverages the spatie/laravel-spatie-laravel-settings-plugin. This allows for both static, environment-specific configuration and dynamic, runtime-configurable settings.

The Docker setup provides another layer of configuration, defining the services, environment, and startup procedures for the application container. This includes setting up cron jobs for background tasks and initializing the database. For development and testing, specific configurations are also defined in composer.json and phpunit.xml respectively.

Environment Configuration (.env)

The primary method for configuring the application is through the .env file located in the project root. This file is created from .env.example on installation and contains essential settings for the Laravel framework and the PriceBuddy application itself. Most common settings are exposed in the application settings page, but advanced settings can be modified here.

Sources: README.md:80-82, docker/php/start-app.sh:4-7

The following table outlines key environment variables defined in config/app.php and README.md:

Variable	Description	Default Value	Source
APP_NAME	The name of the application.	PriceBuddy	config/app.php:15
APP_ENV	The application environment.	production	config/app.php:24
APP_DEBUG	Toggles debug mode, showing detailed error messages.	false	config/app.php:33
APP_VERSION	The application version, updated during CI builds.	development	config/app.php:41
APP_URL	The root URL of the application.	http://localhost	config/app.php:49
APP_TIMEZONE	The default timezone for date/time functions.	UTC	config/app.php:58
APP_LOCALE	The default locale for translation and localization.	en	config/app.php:67
APP_CURRENCY_LOCALE	The default locale for currency formatting.	en_US	config/app.php:71
APP_KEY	A 32-character encryption key for securing values.	null	config/app.php:79
AFFILIATE_ENABLED	Enables or disables the addition of affiliate codes to store URLs.	true (inferred)	README.md:68-71

Application Settings

PriceBuddy provides a user-friendly settings page within the Filament admin panel for managing dynamic application settings. These settings are stored in the database and managed by the spatie/laravel-settings package.

The diagram below illustrates the relationship between the settings data structure (AppSettings.php) and the UI page (AppSettingsPage.php) that manages it.

Scrape Settings

These settings control the behavior of the product price scraping functionality.

Setting	UI Component	Description
scrape_schedule_time	TimePicker	The time of day to fetch product prices.
scrape_cache_ttl	TextInput (numeric)	How many minutes the page HTML will be cached after being scraped.
sleep_seconds_between_scrape	TextInput (numeric)	The number of seconds to wait before fetching the next page to avoid being blocked.
max_attempts_to_scrape	TextInput (numeric)	The maximum number of times to attempt scraping a page before giving up.

Sources: app/Filament/Pages/AppSettingsPage.php:48-73

Locale Settings

These settings define the default localization and currency formatting for the application.

Setting	UI Component	Description	Default
default_locale_settings.locale	Select	The locale for displaying prices and for app translation.	en
default_locale_settings.currency	Select	The default currency for extracting and displaying prices.	USD

Sources: app/Filament/Pages/AppSettingsPage.php:304-316, app/Settings/AppSettings.php:17-21

Logging

This section configures the retention period for application logs.

Setting	UI Component	Description
log_retention_days	Select	How many days to keep logs for. Options range from 7 to 365 days.

Sources: app/Filament/Pages/AppSettingsPage.php:81-93

Notifications

The application supports multiple notification channels. Each can be enabled and configured independently.

Sources: app/Filament/Pages/AppSettingsPage.php:97-193, app/Settings/AppSettings.php:24-26

Email (SMTP)

• SMTP Host: smtp_host
• SMTP Port: smtp_port (default: '25')
• SMTP Username: smtp_user
• SMTP Password: smtp_password
• From Address: from_address
• Encryption: encryption (tls, ssl)

Pushover

• Pushover Token: token

Gotify

• Gotify Server URL: url
• Application Token: token (includes a test action)

Apprise

• Apprise API Server URL: url
• Configuration Token: token (includes a test action)

Integrations

Settings for integrating with external services.

SearXng

This integration allows for automatically searching for additional product URLs.

Setting	UI Component	Description
url	TextInput	The URL of the SearXng instance, including the /search path.
search_prefix	TextInput	Optional text to prepend to the product name when searching.
prune_days	Select	How long to cache parsed search results (1 to 365 days).
max_pages	Select	The number of result pages to fetch from SearXng.

Sources: app/Filament/Pages/AppSettingsPage.php:197-240

Docker & Container Configuration

The project uses Docker for a simplified setup. The docker/php/start-app.sh script orchestrates the container's startup sequence.

This diagram shows the startup process for the application container.

Key steps in the startup script include:

1. Environment Setup: Creates a .env file from .env.example and generates an APP_KEY if one doesn't exist.
2. Storage Initialization: Creates necessary storage directories and links the public storage directory.
3. Database Initialization: Waits for the database to become available, then runs migrations and seeds the database using the buddy:init-db artisan command.
4. Caching: Clears and then warms up various application caches (config, route, events, icons).
5. Service Start: Starts supervisord to manage the Apache web server and the cron scheduler.

The docker/php.dockerfile also defines a cron job that handles background tasks like fetching prices and sending notifications.

Sources: docker/php/start-app.sh, docker/php.dockerfile:23-24

Testing Configuration

The testing environment is configured in phpunit.xml. This file sets specific environment variables to ensure tests run in an isolated and consistent environment.

Variable	Value	Description
APP_ENV	testing	Sets the application environment to testing mode.
APP_MAINTENANCE_DRIVER	file	Uses the file driver for maintenance mode.
BCRYPT_ROUNDS	4	Reduces bcrypt rounds for faster hashing in tests.
CACHE_STORE	array	Uses the in-memory array cache driver.
DB_HOST	tests_db	Specifies the database host for the test database.
MAIL_MAILER	array	Uses the in-memory array mail driver to prevent sending emails.
QUEUE_CONNECTION	sync	Runs queue jobs synchronously instead of dispatching them.
SESSION_DRIVER	array	Uses the in-memory array session driver.

Sources: phpunit.xml:18-27