# PHP Extension Community Library

[![PECL](/public_html/img/pecl.svg "PECL")](https://pecl.php.net)

The PHP Extension Community Library (PECL) (pronounced *pickle*) is a repository
for C and C++ extensions for compiling into the PHP language. This web application
is hosted online at [pecl.php.net](https://pecl.php.net).

## Index

* [About](#about)
* [Bugs and support](#bugs-and-support)
* [Contributing](#contributing)
* [Directory structure](#directory-structure)
* [Installation](#installation)
  * [1. Dependencies](#1-dependencies)
  * [2. Configuration](#2-configuration)
  * [3. Database](#3-database)
  * [4. Apache configuration](#4-apache-configuration)
  * [5. Tests](#5-tests)
* [Credits](#credits)
* [Evolution](#evolution)
* [License and copyrights](#license-and-copyrights)

## About

To learn more how to add new PECL extensions or how to install PECL extensions
using command line tools visit pecl.php.net and PHP manual.

## Bugs and support

Report bugs to [bugs.php.net](https://bugs.php.net/report.php). The PECL project
has a [mailing list](http://news.php.net/php.pecl.dev). More information about
support can be found at [pecl.php.net/support.php](https://pecl.php.net/support.php).

## Contributing

Git repository is located at [git.php.net](https://git.php.net/?p=web/pecl.git).
Contributions to the web application source code are most welcome by forking the
[GitHub mirror repository](https://github.com/php/web-pecl) and sending a pull
request.

```bash
git clone git@github.com:your-username/web-pecl
cd web-pecl
git checkout -b patch-1
git add .
git commit -m "Describe changes"
git push origin patch-1
```

A good practice is to also set the `upstream` remote in case the upstream master
branch updates. This way your master branch will track remote upstream master
branch of the root repository.

```bash
git checkout master
git remote add upstream git://github.com/php/web-pecl
git config branch.master.remote upstream
git pull --rebase
```

## Directory structure

Source code of this application is structured in the following directories:

```bash
<web-pecl>/
 ├─ .git/            # Git configuration and source directory
 └─ bin/             # Command line development tools and scripts
    ├─ cron/         # Various systems scripts to run periodically on the server
    └─ ...
 └─ config/          # Application configuration files
    ├─ app_prod.php  # Production specific environment configuration
    └─ app.php       # Default configuration to be overridden
 └─ include/         # Application helper functions and configuration
    ├─ jpgraph/      # Bundled JpGraph library https://jpgraph.net
    ├─ bootstrap.php # Autoloader, DB connection, container, app initialization
    └─ ...
 └─ public_html/     # Publicly accessible directory for online pecl.php.net
    ├─ css/          # Stylesheets
    ├─ img/          # Images
    ├─ js/           # JavaScript assets
    ├─ packages/     # Uploaded packages releases static files
    ├─ rest/         # Static REST API generated XML files
    └─ ...
 ├─ sql/             # Database schema
 ├─ src/             # Application source code classes
 ├─ templates/       # Application templates
 ├─ tests/           # Application automated tests
 └─ var/             # Temporary generated application files
    ├─ uploads/      # Temporary uploaded packages releases
    └─ ...
 ├─ vendor/          # Dependencies generated by Composer
 ├─ .env.dist        # Distributed environment variables file for development
 ├─ composer.json    # Composer dependencies and project meta definition
 ├─ composer.lock    # Dependencies versions currently installed
 ├─ phpunit.xml.dist # PHPUnit's default XML configuration
 └─ ...
```

## Installation

The pecl.php.net is written for PHP 7.2+, MySQL, and Apache 2.4.

### 1. Dependencies

Install dependencies with Composer:

```bash
composer install
```

### 2. Configuration

Application configuration is located in the `config` directory. The main file
`config/app.php` includes default application settings. When installing
application with Composer in the development environment, the `.env` file with
environment variables is created from the `.env.dist`.

If it hasn't been created yet copy default distributed settings manually and
adjust it for your development environment:

```bash
cp .env.dist .env
```

The `config/app_prod.php` is a configuration file for production environment at
pecl.php.net. Configuration precedence order is (first that is encountered):

* Environment variables (either set in the `.env` file for development or via
  server for production).
* `config/app_prod.php`
* `config/app.php`

### 3. Database

The database schema is available in the SQL file
[pecl_full_structure_prod.sql](/sql/pecl_full_structure_prod.sql).

To create the database, run `make create`. To remove the created database run
`make destroy` in the `sql` directory. On systems where `make` is not available,
for example, FreeBSD, use `gmake` instead.

Create demo data fixtures for the development environment:

```bash
bin/console app:generate-fixtures
```

This will create user `admin` with password `password` to be able to login on
localhost.

### 4. Apache configuration

These are typical Apache directives you need to set up for a development site.
This installation has PEAR installed in `/usr/share/pear`.

```apacheconf
<VirtualHost *>
    ServerName pecl.localhost

    DocumentRoot /path/to/pecl/public_html
    DirectoryIndex index.php index.html

    php_value include_path .:/path/to/pecl/include:/usr/share/pear
    php_value auto_prepend_file pear-prepend.php

    ErrorDocument 404 /error/404.php

    Alias /package /path/to/pecl/public_html/package-info.php

    RewriteEngine On
    RewriteRule   /rss.php              /feeds/latest.rss [R=301]

    # Rewrite rules for the RSS feeds
    RewriteRule   /feeds/(.+)\.rss$ /feeds/feeds.php?type=$1

    # Rewrite rules for the account info /user/handle
    RewriteRule   /user/(.+)$ /account-info.php?handle=$1

    # Rewrite rule for account info /package/pkgname/version
    RewriteRule   /package/(.+)/(.+)/windows$ /package-info-win.php?package=$1&version=$2
    RewriteRule   /package/(.+)/(.+)$ /package-info.php?package=$1&version=$2
    RewriteRule   /package/(.+)$ /package-info.php?package=$1

    <Location /get>
        ForceType application/x-httpd-php
    </Location>
</VirtualHost>
```

### 5. Tests

In development environment after installing development dependencies run
`phpunit` to execute application unit tests:

```bash
phpunit
```

## Credits

This page would not be possible without a continuous effort of maintainers of
PECL extensions, open source contributors, hosting infrastructure sponsors, and
people involved in maintaining this site. Big thanks to
[everyone involved](https://pecl.php.net/credits.php).

## Evolution

PECL, formerly known as *PHP Extension Code Library*, has been initially started
under the [PEAR](https://pear.php.net) umbrella. In October 2003 it has been
renamed to *PHP Extension Community Library* and has evolved from the
[pearweb](https://github.com/pear/pearweb) application. Under the hood, pearweb
uses a set of utility classes called *Damblan* (name derived from the
Nepalese summit [Ama Dablam](https://www.summitpost.org/ama-dablam/150234)) by a
lead developer Martin Jansen.

Since then, PECL related services have been moved to online community repository
[pecl.php.net](https://pecl.php.net/) exclusively dedicated to extensions written
in C programming language to efficiently extend the PHP language. Today, many
widely used PECL extensions written in C and C++ are hosted and distributed via
PECL.

## License and copyrights

This repository is released under the [PHP license](LICENSE). Visit the
[copyright page](https://pecl.php.net/copyright.php) for more information.