README

A versatile logging framework for PHP. This project is a fork of Apache log4php, modernized for PHP 8.0+ compatibility.

Installation
Basic Usage
Documentation
Contributing
Development Setup
Running Tests
Project Structure
License

Installation

Install via Composer:

composer require daltondiaz/log4php

Basic Usage

<?php
require_once 'vendor/autoload.php';

// Configure logger
\Logger::configure('config.xml');

// Get a logger instance
$logger = \Logger::getLogger(__CLASS__);

// Log messages
$logger->info('This is an info message');
$logger->error('This is an error message');
$logger->debug('Debug information');

Documentation

For detailed documentation, visit the Apache log4php project website:
http://logging.apache.org/log4php/

Contributing

We welcome contributions! Whether it's bug fixes, new features, improvements, or documentation, please follow the guidelines below.

Development Setup

Prerequisites

PHP: 8.0 or higher
Composer: Latest version
Git: For version control

Clone and Setup

# Clone the repository
git clone https://github.com/daltondiaz/log4php.git
cd log4php

# Install dependencies (including dev dependencies)
composer install --ignore-platform-req=ext-mongodb

# The --ignore-platform-req flag is needed due to MongoDB extension version constraints

Project Structure

log4php/
├── src/
│   ├── main/php/          # Main source code
│   │   ├── appenders/     # Output appenders (File, Database, Email, etc.)
│   │   ├── layouts/       # Message format layouts
│   │   ├── filters/       # Log filtering
│   │   └── *.php          # Core classes (Logger, LoggerLevel, etc.)
│   ├── test/php/          # PHPUnit test files
│   │   ├── appenders/     # Appender tests
│   │   ├── configurators/ # Configuration tests
│   │   ├── layouts/       # Layout tests
│   │   ├── renderers/     # Renderer tests
│   │   └── *.php          # Core class tests
│   ├── resources/         # Test configuration files
│   └── examples/          # Usage examples
├── vendor/                # Composer dependencies
├── phpunit.xml           # PHPUnit configuration
├── composer.json         # Project dependencies
└── README.md            # This file

Running Tests

Before You Start

Make sure you've completed the Development Setup section.

Run All Tests

# Run the complete test suite
./vendor/bin/phpunit --verbose --testdox

Run Specific Tests

# Run a single test file
./vendor/bin/phpunit --testdox src/test/php/LoggerLevelTest.php

# Run tests for a specific component
./vendor/bin/phpunit --testdox src/test/php/appenders/

# Run with verbose output
./vendor/bin/phpunit --testdox

Generate Coverage Report

# Generate HTML coverage report
./vendor/bin/phpunit --coverage-html target/test/report

Coverage reports will be generated in target/test/report/index.html

Test Status

✅ 261 tests - All passing
✅ 967 assertions - All passing
⚠️ 46 deprecation warnings - Related to PHPUnit 10 compatibility (backward compatible)
⏭️ 13 tests skipped - Optional extensions not available

How to Contribute

1. Create an Issue First (Recommended)

Before starting work, create an issue to discuss:

Bug reports (with reproduction steps)
Feature requests (with use cases)
Improvements or refactoring ideas

This helps ensure your work aligns with project goals.

2. Fork and Branch

# Fork the repository on GitHub

# Clone your fork
git clone https://github.com/YOUR-USERNAME/log4php.git
cd log4php

# Add upstream remote
git remote add upstream https://github.com/daltondiaz/log4php.git

# Create a feature branch
git checkout -b feature/your-feature-name
# or for bug fixes
git checkout -b fix/your-bug-fix-name

3. Development Workflow

# Install dependencies and ignore mongo if you dont use it
composer install --ignore-platform-req=ext-mongodb

# Make your changes in src/main/php/

# If adding functionality, also add tests in src/test/php/

4. Write Tests

For any new functionality or bug fixes, add corresponding test cases:

<?php
// Example: src/test/php/YourNewFeatureTest.php
class YourNewFeatureTest extends \PHPUnit\Framework\TestCase
{
    public function testYourNewFeature()
    {
        // Arrange
        $object = new YourClass();
        
        // Act
        $result = $object->yourMethod();
        
        // Assert
        self::assertEquals('expected', $result);
    }
}

Run your tests to ensure they pass:

./vendor/bin/phpunit src/test/php/YourNewFeatureTest.php

5. Code Style Guidelines

Follow PSR-12 coding standards
Use meaningful variable and method names
Add PHPDoc comments for public methods
Keep methods focused and single-responsibility

Example:

<?php
/**
 * Get the logger instance for the specified class
 *
 * @param string $class The class name
 * @return Logger The logger instance
 */
public static function getLogger($class)
{
    // Implementation
}

6. Run Full Test Suite

Before submitting, ensure all tests pass:

# Run entire test suite
./vendor/bin/phpunit

# Should see: WARNINGS! (46 warnings are expected and backward compatible)
# Should NOT see: FAILURES or ERRORS

7. Commit Changes

# Stage your changes
git add .

# Commit with descriptive message for features and changes
git commit -m "feat: description of your changes"

# Commit with descriptive message for bug fix 
git commit -m "fix: description of your fix"

# Commit with descriptive message for refactor
git commit -m "refactor: description of your refactor"

# Commit with descriptive message for any change or new doc
git commit -m "docs: description of your refactor"

# Push to your fork
git push origin feature/your-feature-name

Commit Message Guidelines:

Use imperative mood ("Add" not "Added", "Fix" not "Fixed")
Start with a capital letter
Keep the subject line under 50 characters
Add detailed description in the body if needed

Examples:

feat: Add support for custom appender configuration
fix: Fix timezone issue in date formatting
docs: Update LoggerLevel documentation
refactor: Refactor LoggerConfigurator for better readability

8. Create a Pull Request

Go to your fork on GitHub
Click "New Pull Request"
Select main as the base branch
Provide a clear title and description
Reference any related issues (e.g., "Fixes #123")
Wait for review and CI checks to pass

Pull Request Template:

## Description
Brief description of your changes

## Related Issue
Fixes #123 (if applicable)

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update

## How to Test
Steps to verify your changes work

## Checklist
- [ ] Tests pass locally
- [ ] Added/updated tests for new functionality
- [ ] Updated documentation if needed
- [ ] Followed code style guidelines

9. Respond to Feedback

Be open to suggestions and constructive criticism
Update your PR based on review feedback
Push additional commits to address issues (no need to force push)

Testing New Appenders or Features

If you're adding a new appender or layout:

# 1. Create a test file
touch src/test/php/appenders/YourNewAppenderTest.php

# 2. Write comprehensive tests
# 3. Run your tests
./vendor/bin/phpunit --testdox src/test/php/appenders/YourNewAppenderTest.php

# 4. Run full suite to ensure no regressions
./vendor/bin/phpunit --testdox

Common Development Tasks

Add a New Appender

Create: src/main/php/appenders/LoggerAppenderYourName.php
Extend: LoggerAppender
Implement: append() method
Create tests: src/test/php/appenders/LoggerAppenderYourNameTest.php

Add a New Layout

Create: src/main/php/layouts/LoggerLayoutYourName.php
Extend: LoggerLayout
Implement: format() method
Create tests: src/test/php/layouts/LoggerLayoutYourNameTest.php

Report a Bug

Create an issue with:

Clear title describing the bug
PHP version and environment details
Minimal code to reproduce
Expected vs actual behavior
Error messages or stack traces

License

Licensed under the Apache License, Version 2.0. See the LICENSE file for details.

Getting Help

Questions? Create a GitHub Discussion or Issue
Found a bug? Open an Issue with reproduction steps
Have an idea? Share it in a GitHub Discussion
Documentation unclear? Help us improve by reporting it

Thank you for contributing! 🎉

daltondiaz / log4php

Maintainers

Package info

Statistics

Security