mpernia/phar-skeleton

A skeleton project to build a PHAR package in PHP

1.0.1 2025-03-09 16:44 UTC

Requires

• php: >=8.2

MIT

• Maikel Enrique Pernia Matos

• project
• Skeleton
• phar

README

Phar Skeleton is a simple starter project for building a .phar package in PHP.
This repository provides a basic structure to create, compile, and distribute your PHP application as a PHAR archive.

Contents

• Requirements
• Features
• Project Structure
• Getting Started
  • Environment Variables
• Usage
  • Build with Makefile
  • Build with Composer
• Run or distribute the PHAR file
• Error Handling
• Contributing
• License

Requirements

• PHP 8.2 or higher
• PHP phar.readonly setting must be disabled
• make command available in your system

Features

• Basic Composer configuration (type = "project").
• PSR-4 autoloading support.
• Simple build script example (src/Example.php).
• Example CLI script (build/app.phar).

Project Structure

.
├── .env               # Environment variables
├── Makefile           # Build automation
├── README.md          # This file
├── bin/
│   └── builder.php    # PHAR builder script
└── src/
    ├── index.php      # Main application file
    └── ...            # Other PHP source files

Getting Started

1. Install this skeleton (via Composer or by downloading/cloning this repository).
2. Customize your package:
   • Update composer.json with your details.
   • Modify src/ files to include your application logic.
   • Edit a file .env to set environment variables.

     BUILD_DIR=build
     PHAR_NAME=app.phar

3. Build your PHAR:
   • Run composer compile or directly make.
   • This will generate a app.phar file in the project.
   • The PHAR file will be created in the specified build directory (default: ./build/app.phar).
4. Run or test your PHAR:
   • Run php build/app.phar or build/app.phar to execute the PHAR file.

Environment Variables

• BUILD_DIR: Directory where the PHAR file will be created
• PHAR_NAME: Name of the output PHAR file

Usage

Build with Makefile

The project includes a Makefile with several commands to help you build the PHAR file:

# Clean and build (recommended)
make all

# Only clean the build directory
make clean

# Only build the PHAR file
make build

# Show available commands
make help

Build with Composer

You can also use Composer to build the PHAR file:

composer compile

Additional Makefile Commands

The following commands have been added to the Makefile:

• check-index: Ensures that the public/index.php file exists. If it does not, it creates the file with a default message.
• docker-composer-install: Runs composer install inside the Composer container to install dependencies.
• docker-build-app: Executes make build inside the application container to build the PHAR file.
• dir-app: Opens a bash shell in the application container for direct access to the app directory.

Run or distribute the PHAR file

• You can run the PHAR file directly:

  php build/app.phar

  Or:

  php build/app.phar

• You can also distribute the PHAR file to other machines or environments, so they can run the application without needing the full source.

Error Handling

• If the .env file is missing or incomplete, the build process will show an error message with the required variables
• Build errors will be displayed with appropriate error messages and exit codes

Contributing

Feel free to open issues or submit pull requests if you have any suggestions or improvements.

1. Fork the repository
2. Create your feature branch
3. Commit your changes
4. Push to the branch
5. Create a new Pull Request

License

MIT License. See the LICENSE file for more details.