README

esanj/public-pages is a Laravel package that gives your application a clean, ready-to-use home page and a complete set of HTTP error pages (400, 401, 403, 404, 419, 429, 500, 502, 503, 504), with bundled assets (CSS, background image), built-in English & Persian translations, and full control through a simple config file.

Everything works out of the box. You only publish files when you want to customize them.

✨ Features

• ✅ Pre-designed error pages for the 10 most common HTTP status codes
• 🏠 Optional, configurable home page route
• 📁 Bundled front-end assets (CSS + background image)
• 🌐 Multi-language support (English & Persian included, RTL-aware)
• 🎨 Fully customizable — publish and override views, assets, config & translations
• ⚡ Zero configuration required to get started

📋 Requirements

📦 Installation

1. Install via Composer:

composer require esanj/public-pages

That's it — the package auto-registers itself. The home page and error pages are already active.

2. (Optional) Publish files you want to customize:

php artisan publicpages:install

With no options, this publishes everything (views, assets, translations, and config). See Commands to publish only what you need.

🗂️ What Gets Published

File tree after a full install:

resources/
└── views/
    ├── vendor/publicpages/
    │   └── home.blade.php
    └── errors/
        ├── layout.blade.php
        ├── 404.blade.php
        ├── 500.blade.php
        └── ...
public/
└── assets/vendor/public-pages/
    ├── style.css
    └── background.png
lang/
├── en/publicpages.php
└── fa/publicpages.php
config/
└── esanj/public_pages.php

🧩 Commands

publicpages:install also accepts flags to publish only part of the package:

php artisan publicpages:install --views     # views only
php artisan publicpages:install --assets    # assets only
php artisan publicpages:install --lang      # translations only
php artisan publicpages:install --config    # config only
php artisan publicpages:install --all       # everything (same as no flag)

ℹ️ publicpages:install always overwrites existing files, so you can re-run it any time to pull in updates.

You can also publish directly with Laravel's vendor:publish using the package tags:

php artisan vendor:publish --tag=esanj-public-pages-views

⚙️ Configuration

Publish the config file:

php artisan publicpages:publish-config

This creates config/esanj/public_pages.php. The full default config:

<?php

return [
    // Name shown on the home and error pages.
    'app_name' => env('APP_NAME', 'eSanj'),

    // Home page route.
    'home' => [
        'enabled' => env('PUBLIC_PAGES_HOME_ENABLED', true), // register the home route?
        'path'    => env('PUBLIC_PAGES_HOME_PATH', '/'),     // URI for the home page
        'view'    => 'publicpages::home',                    // view to render
    ],

    // Middleware applied to the package routes.
    'routes' => [
        'middleware' => ['web'],
    ],

    // Custom error pages.
    'errors' => [
        'enabled' => env('PUBLIC_PAGES_ERRORS_ENABLED', true), // use package error pages?
        'layout'  => 'errors.layout',                          // base layout for error views
    ],
];

Common tweaks

Disable the home route (you provide your own /):

PUBLIC_PAGES_HOME_ENABLED=false

Change the home page path:

PUBLIC_PAGES_HOME_PATH=/welcome

Use Laravel's default error pages instead of the package's:

PUBLIC_PAGES_ERRORS_ENABLED=false

Change the app name shown on the pages:

APP_NAME="My Startup"

Apply extra middleware to the home route — edit config/esanj/public_pages.php:

'routes' => [
    'middleware' => ['web', 'auth'],
],

🔁 To reset the configuration, delete config/esanj/public_pages.php and run php artisan config:clear. The package falls back to its built-in defaults automatically.

🌐 Localization

Translations live in lang/{locale}/publicpages.php and ship with English (en) and Persian (fa). The error layout automatically switches to RTL when the app locale is fa.

Publish them to customize:

php artisan publicpages:publish-lang

File structure:

<?php

return [
    'home' => [
        'title'       => 'Welcome to our website',
        'description' => 'This is the home page provided by the esanj/public-pages package.',
    ],

    'labels' => [
        'copyright' => '© :year :brand Platform. All rights reserved.',
    ],

    'errors' => [
        '404' => [
            'title'   => 'Page Not Found',
            'message' => "The page or resource you're looking for was not found.",
        ],
        '500' => [
            'title'   => 'Internal Server Error',
            'message' => 'An internal server error occurred. Please try again later.',
        ],
        // ... other status codes
    ],
];

Reference any string in Blade with the publicpages::publicpages.* key:

{{ __('publicpages::publicpages.errors.404.title') }}

Add another locale by creating lang/{locale}/publicpages.php (e.g. lang/es/publicpages.php) with the same structure.

➕ Adding a New Error Page

Suppose you want to support 505 HTTP Version Not Supported.

1. Add the translations in lang/{locale}/publicpages.php under errors:

'505' => [
    'title'   => 'HTTP Version Not Supported',
    'message' => 'The server does not support the HTTP protocol version used in the request.',
],

2. Create the view resources/views/errors/505.blade.php:

@extends('errors::layout')

@php
    $code = 505;
@endphp

The shared errors::layout reads $code and pulls the matching title/message from your translation file — no other wiring needed.

🎨 Customizing the Look

• Views — after publishing, edit resources/views/errors/layout.blade.php (the shared error layout) or resources/views/vendor/publicpages/home.blade.php (the home page).

• Styles — edit public/assets/vendor/public-pages/style.css and the background.png next to it.

• Use your own error layout — point the config at it:

  'errors' => [
      'layout' => 'layouts.error-base',
  ],

  then create resources/views/layouts/error-base.blade.php with your own markup.

📖 For a complete, beginner-friendly, step-by-step walkthrough, see docs/GUIDE.md.

📄 License

MIT © 2025 — Esanj Team