Introduction

Overview

ValPress is a modern, Laravel-based content management system (CMS) built as a pragmatic alternative to WordPress. It combines Laravel's developer-first tooling with a familiar CMS experience: plugins, themes, hooks (actions and filters), a clean admin panel, and a flexible content model. ValPress targets teams that want the productivity of a CMS without compromising on code quality, performance, or maintainability.

ValPress embraces Laravel conventions: service container, middleware, routing, Blade, Eloquent, queues, and the full ecosystem of packages — while adding a lightweight CMS layer for content, media, theming, and extensibility.

Why It Matters

• Developer experience: Build with Laravel patterns you already know — no custom DSLs or hidden magic.
• Extensibility: Plugins, themes, and a robust hooks system allow clean customization without editing core files.
• Performance: Cache-friendly architecture and an intentionally small core keep request handling fast.
• Maintainability: Clear separation of concerns (core vs. plugins/themes), testable code, and Laravel-native tooling.
• Migration-friendly: Familiar database structure and Eloquent models ease data migrations and imports/exports.

How It Works

At a high level, ValPress bootstraps a Laravel application and layers CMS features on top.

Conceptual architecture (text diagram):

• HTTP Kernel (Laravel)
  • Global middleware (auth, CSRF, caching)
  • Route handling (web/admin)
• ValPress Core
  • Post types and taxonomies (Eloquent models, repositories)
  • Options/settings (configurable key-value storage)
  • Media management
  • Admin UI (Blade views + policies/gates)
  • Hook system (actions/filters)
• Extensions
  • Plugins (business features, integrations)
  • Themes (presentation, Blade templates, assets)

Request lifecycle (simplified):

1. Request enters Laravel's HTTP kernel and passes middleware.
2. Routes resolve to controllers (core or plugin-provided via registration APIs).
3. Hooks fire (e.g., action events around rendering or admin screens).
4. Controller composes data (Eloquent), renders Blade view (theme/admin), and returns a response.
5. Response may be filtered via output-related hooks.

Usage

Use ValPress in two primary modes:

1. Site building without custom code

   • Install ValPress, choose a theme, enable plugins.
   • Configure content types, menus, and settings from Admin.

2. Application development with custom code (recommended for teams)

   • Create a plugin for domain-specific features and integrations.
   • Register routes, controllers, Blade views, and migrations inside your plugin.
   • Use hooks to extend or alter behavior without forking core.

What you need to know first:

• Laravel basics: routes, controllers, Blade, Eloquent, config, env.
• ValPress extensions: plugins (logic), themes (presentation), hooks (glue).

Advanced Usage

• Custom post types (CPTs): Register programmatically in a plugin to model domain entities (e.g., Events, Products). CPTs integrate with taxonomies, permalinks, and admin listing screens.
• Admin customization: Use filters such as valpress_admin_menu_items to contribute structured menus and submenus. Use actions to enqueue assets on specific screens, or to hook into saving/publishing flows.
• Routing: Keep plugin routes namespaced and behind relevant middleware (auth, authorization). Prefer controller classes to closures for testability.
• Caching: Leverage Laravel caches for expensive queries; clear affected caches in relevant action hooks.
• Testing: Place plugin tests under public/plugins/{slug}/tests and run via php artisan test

Best Practices

• Never modify core files; implement features in plugins or themes.
• Keep plugins focused: one responsibility per plugin to ease maintenance and updates.
• Use hooks for integration points; avoid hard-coding references to other plugins.
• Follow PSR-12 and Laravel naming conventions; prefer dependency injection.
• Localize all user-facing strings with __() and @lang for i18n.
• Validate and authorize all admin actions; use policies/gates where appropriate.
• Ship database migrations with plugins that own tables; write idempotent migrations.
• Keep Blade templates slim; push data preparation to controllers/view models.

Common Mistakes

• Editing files under app/Core or vendor directories — customization should live in plugins/themes.
• Registering routes without middleware, exposing admin endpoints publicly.
• Echoing raw HTML without sanitization; always escape or trust only sanitized content.
• Bypassing hooks and tightly coupling plugins; prefer decoupled communication through actions/filters.
• Mixing presentation and business logic in Blade views.

Summary

ValPress brings a Laravel-native development model to a CMS context. Build features as plugins, present them with themes, and connect everything through a simple hooks system. You retain the full power of Laravel — routing, middleware, Blade, Eloquent — while gaining a focused CMS layer that stays out of your way. This introduction set expectations and provided working examples you can adapt as you build.

Compatibility and versioning note: This document targets ValPress 1.x. When upgrading to 2.x, review the release notes for breaking changes, particularly around hook names, admin UI contracts, and any modified configuration keys. Prefer forward-compatible patterns (namespaced route names, DI in controllers, idempotent migrations) to reduce friction when upgrading.