Geeftlist

Geeftlist is a self‑hosted, collaborative gift‑management web application written primarily in PHP with a modest front‑end stack (HTML, SCSS/CSS, minimal JavaScript). The project is built around a classic MVC pattern, leveraging PHP’s procedural capabilities to keep the codebase lightweight while still offering a full REST‑style API for external integration. The core of Geeftlist is a relational database (MySQL/MariaDB) that stores users, lists, items, and purchase history, with the schema exposed through a set of PHP data‑access objects. This design allows developers to embed Geeftlist into existing PHP ecosystems or expose its data to micro‑services via the provided JSON endpoints.

Architecture & Technical Stack

• Language: PHP 8.x (strict types, namespaced classes)
• Frameworks & Libraries:
  • Custom lightweight MVC framework (no heavy frameworks like Laravel or Symfony)
  • SCSS compiled to CSS for styling; minimal JavaScript (vanilla) for interactivity
  • Composer‑managed dependencies (e.g., PHPMailer, Symfony/Filesystem)
• Database: MySQL/MariaDB (schema migrations handled via SQL scripts in /migrations)
• Containerization: Official Docker image (ghcr.io/nanawel/geeftlist) with docker-compose support; Dockerfile uses multi‑stage builds to keep the runtime image slim.
• Web Server: Nginx (or Apache) with PHP‑FPM; reverse proxying is optional for HTTPS termination.

Core Capabilities & Developer APIs

Geeftlist exposes a RESTful API under /api/* that allows CRUD operations on lists, items, and users. Authentication is handled via session cookies or an optional API token system (JWT‑like tokens stored in the database). Endpoints include:

• GET /api/lists – list all gift lists for the authenticated user
• POST /api/items – create a new item in a specified list
• PATCH /api/items/{id} – update quantity, status, or notes

The API is fully documented in the /docs/api.md file, with example payloads and error codes. Webhooks can be configured per list to notify external services on events such as “item purchased” or “list updated.” Developers can also hook into the PHP event system to extend behavior (e.g., send Slack notifications when a gift is bought).

Deployment & Infrastructure

Geeftlist’s lightweight architecture makes it suitable for Docker‑based deployments on any LAMP stack. The Docker image is under 200 MB, and the docker-compose.yml file demonstrates a production‑ready configuration with separate services for PHP‑FPM, Nginx, and MySQL. The application is stateless apart from the database, allowing horizontal scaling by spinning up additional PHP workers behind a load balancer. For high‑availability, developers can use MariaDB Galera or MySQL Group Replication to replicate the database across nodes.

Integration & Extensibility

The codebase is intentionally modular. The src/ directory contains separate namespaces for models, controllers, and services, making it easy to override or extend functionality. Custom plugins can be added by placing PHP classes in /plugins/ and registering them via the config/plugins.php file. Geeftlist also offers a CLI tool (bin/geeftlist) for batch operations (e.g., importing CSV lists, generating reports). Because the UI is built with plain HTML and minimal JavaScript, developers can replace or augment the front‑end with frameworks like Vue.js or React without touching the core logic.

Developer Experience

• Configuration: Environment variables (.env) control database credentials, mail server settings, and API token secrets.
• Documentation: The repository includes a comprehensive README.md, an API reference, and inline PHPDoc comments.
• Community: The project has a small but active issue tracker; contributors can submit pull requests for new features or bug fixes. The license is MIT, encouraging reuse and modification.

Use Cases

• Family Gift Planning: Teams of relatives can collaboratively build a shared gift list, with real‑time updates and purchase notifications.
• Event Management: Wedding or party planners can use Geeftlist to track registry items and attendee contributions.
• Small Business: Boutique owners can create wish lists for customers, integrating with their existing PHP e‑commerce stack.

Advantages Over Alternatives

• Performance: A lightweight PHP core with minimal dependencies results in low memory usage and fast request handling.
• Flexibility: The absence of a monolithic framework means developers can drop in only the components they need.
• Licensing: MIT license allows commercial use without royalties or copyleft constraints.
• Self‑Hosting Control: Full access to the database and codebase ensures compliance with privacy regulations (GDPR, CCPA).

Geeftlist offers a solid foundation for developers seeking a self‑hosted, extensible gift‑management solution that can be integrated into existing PHP infrastructures with minimal friction.