README

esanj/public-pages is a Laravel package providing clean and customizable public-facing pages such as error views (404, 500, 403, etc.), along with localized messages and frontend assets (CSS/JS/images).

Built for maintainability and full flexibility, this package integrates quickly into any Laravel 10+ or 12 project with a few commands.

✨ Features

• ✅ Pre-designed error templates (404, 500, 403, etc.)
• 📁 Includes public assets (CSS, icons…)
• 🌐 Supports multi-language via Laravel's lang system
• 🎨 Full ability to customize views, assets, config & messages
• ⚡ Works out-of-the-box with Blade or Livewire
• 🧼 Clean UI with minimal setup time

📦 Installation

1️⃣ Install via Composer:

composer require esanj/public-pages

2️⃣ Then publish the views and assets with:

php artisan publicpages:install

This command will publish:

Blade views → resources/views/vendor/publicpages/

Assets → public/assets/vendor/publicpages/

You’re ready to go!

📂 File Structure (after install)

resources/
├── views/
│   ├── vendor/publicpages/home.blade.php
│   └── errors/
│       ├── 404.blade.php
│       ├── 500.blade.php
│       └── ...
public/
├── assets/
    ├── vendor/
        ├── public-pages/
            ├── style.css
            └── background.png

🧩 Commands Overview

⬇️ Installs views and assets (required)

php artisan publicpages:install

📄 Publishes ONLY views + assets

php artisan publicpages:publish-views

🌐 Publishes language/translation files

php artisan publicpages:publish-lang

⚙️ Publishes config file

php artisan publicpages:publish-config

You can rerun them anytime using --force.

🌐 Localization

This package supports multiple languages.

To publish translation files:

php artisan publicpages:publish-lang

This will create:

📄 /lang/*/publicpages.php

Sample structure:

return [
   'errors' => [
         '404' => [
            'title' => 'Page not found',
            'message' => 'The page you’re looking for does not exist.',
         ],
         '500' => [
            'title' => 'Internal Server Error',
            'message' => 'Something went wrong. Please try again later.',
         ],
         // Add more codes...
   ]
];

You can create files for other locales (e.g. fa, es, etc.) as needed.

➕ Add New Error Page

To support a new status code like 505 (HTTP Version Not Supported):

1️⃣ Add entry in your lang file:

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

2️⃣ Then create a new blade file:

resources/views/errors/505.blade.php

This file can extend the base layout and use the dynamic error message like so:

@extends('errors::layout')

@php
    $code = 505;
@endphp

📥 Publishing Config

To publish the configuration file:

php artisan publicpages:publish-config

This creates:

config/publicpages.php

⚙️ Available Options

🏷️ Application Name

Controls the app name displayed on public and error pages.

'app_name' => env('APP_NAME', 'eSanj'),

💡 Tip: Override via .env:

APP_NAME="My Custom App"

🏠 Home Page Configuration

Controls whether the package registers a home route and where it points.

'home' => [
   'enabled' => env('PUBLIC_PAGES_HOME_ENABLED', true), // Enable/disable the home route registration
   'path' => env('PUBLIC_PAGES_HOME_PATH', '/'),        // URI path for the home page
   'view' => 'publicpages::home',                       // Blade view to render
],

🔧 Example: Disable home route

In .env:

PUBLIC_PAGES_HOME_ENABLED=false

🔧 Example: Change home path to:

• /welcome

In .env:

PUBLIC_PAGES_HOME_PATH=/welcome

Or directly in config:

'path' => '/welcome',

🔧 Example: Use custom view

'view' => 'pages.custom-home',

🛣️ Route Middleware

Define which middleware groups apply to public pages routes.

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

🔧 Example: Add guest middleware

'middleware' => ['web', 'guest'],

❌ Error Pages Configuration

Controls whether custom error pages are used and which layout they extend.

'errors' => [
    'enabled' => env('PUBLIC_PAGES_ERRORS_ENABLED', true),
    'layout' => 'errors.layout',
],

Options:

Key Type Default Description enabled bool true Enable/disable custom error pages layout string 'errors.layout' Base Blade layout for error views

🔧 Example: Disable custom error pages

In .env:

PUBLIC_PAGES_ERRORS_ENABLED=false

🔧 Example: Use custom error layout

'layout' => 'layouts.error-base',

Then create resources/views/layouts/error-base.blade.php with your custom structure.

📋 Full Config Reference

Here’s the complete default config structure:

<?php

return [
    // App name shown on pages
    'app_name' => env('APP_NAME', 'eSanj'),

    // Home page settings
    'home' => [
        'enabled' => env('PUBLIC_PAGES_HOME_ENABLED', true),
        'path' => env('PUBLIC_PAGES_HOME_PATH', '/'),
        'view' => 'publicpages::home',
    ],

    // Route configuration
    'routes' => [
        'middleware' => ['web'],
    ],

    // Error pages settings
    'errors' => [
        'enabled' => env('PUBLIC_PAGES_ERRORS_ENABLED', true),
        'layout' => 'errors.layout',
    ],
];

🎯 Common Use Cases

✅ Disable home route (using your own routes)

PUBLIC_PAGES_HOME_ENABLED=false

✅ Change home page path

PUBLIC_PAGES_HOME_PATH=/start

✅ Use Laravel’s default error pages

PUBLIC_PAGES_ERRORS_ENABLED=false

✅ Customize app name

APP_NAME="My Startup"

✅ Apply auth middleware to home route In config/esanj/publicpages.php:

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

🔄 Reverting to Defaults

If you want to reset configuration:

Delete config/esanj/publicpages.php

Clear config cache:

php artisan config:clear

The package will use built-in defaults automatically.

📦 Publishing Summary

You can always run a specific tag manually:

Tag Includes

public-pages-views 🎨 Views only

public-pages-assets 🧩 Public assets only

public-pages-lang 🌐 Language files

public-pages-config ⚙️ Configuration file

Example:

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

📄 License

MIT © 2025 — Esanj Team