PEAR For The Masses

Slide 1: PEAR for the masses Stephan Schmidt Metrix Internet Design GmbH, Germany O’Reilly Open Source Convention July 26–30, 2004

Slide 2: Agenda • About the Speaker • What is PEAR • The Website • Obtaining and Installing PEAR • The PEAR Community • Using PEAR Components • Contributing to PEAR • The Future of PEAR Stephan Schmidt <schst@php.net> Slide 2 of 39

Slide 3: About the speaker • Working for Metrix Internet Design GmbH in Karlsruhe, Germany • PHP since version 3 • Co-founder of PHP Application Tools (www.php- tools.net) • Member of the PEAR QA-Core Team • Active Contributor to PEAR (Lead developer of 11 packages) • Working on C-Extensions for PHP • Regular speaker at conferences and author for various magazines Stephan Schmidt <schst@php.net> Slide 3 of 39

Slide 4: What is PEAR? Of course, but also… Stephan Schmidt <schst@php.net> Slide 4 of 39

Slide 5: What is PEAR? PEAR is short for PHP Extension and Application Repository, and was founded in 1999 by Stig S. Bakken. PEAR is several things: • A structured library of open-source code for PHP developers. • The PEAR website • The PEAR Community and Mailinglists • The PEAR installer Stephan Schmidt <schst@php.net> Slide 5 of 39

Slide 6: The Code Library • Organized in Categories (Database, File Formats, HTTP, Images, XML, …) • Categories contain Packages (HTTP_Client, MP3_ID, XML_Parser, …) • Packages are separate projects with their own development team, release cycle and documentation • Relations between packages solved by dependencies (HTTP_Client needs HTTP_Request) Stephan Schmidt <schst@php.net> Slide 6 of 39

Slide 7: PEAR packages • Currently more than 230 packages are available • Packages contain – PHP Files (mostly OOP-Code) – Examples – Unit Tests (either phpt or PHP_Unit) – Documentation (in plain text) • Releases have a state (devel, alpha, beta, stable) to indicate the maturity of the package • All packages and releases are stored in one central database at pearweb. • Based on open licenses like the PHP or LGPL licenses (no GPL allowed) Stephan Schmidt <schst@php.net> Slide 7 of 39

Slide 9: The PEAR Website Stephan Schmidt <schst@php.net> Slide 9 of 39

Slide 10: The PEAR Website (2) • Allows users to browse categories and packages using the package browser • Provides information about each package – Short description – Maintainers – List of releases – Changelog – Auto-generated API documentation • Each release may be downloaded as a TGZ archive Stephan Schmidt <schst@php.net> Slide 10 of 39

Slide 11: The PEAR Website (3) The Website also provides: • Online documentation (mainly English, some translations) • Downloadable documentation • Bug Tracking System • Account list to browse all developers • Possibility to contact each maintainer using an HTML form • Support resources (links to mailing list archives and tutorials) Stephan Schmidt <schst@php.net> Slide 11 of 39

Slide 12: The PEAR Website for Developers Developer features of the website include: • Online proposal system for new packages (PEPr) • Registering new packages • Uploading new releases • Editing package information and maintainers The PEAR Website will promote new packages by announcing them on the website and mailing list. Stephan Schmidt <schst@php.net> Slide 12 of 39

Slide 13: Interlude: What is PECL? • PHP Extension Community Library • Sister project of PEAR for C Extensions • Uses the PEAR infrastructure and installer • Governed by King Wez (Furlong) • Official repository for PHP Extensions • Long term plan includes moving all PHP Extensions from the source tree to PECL to allow separate release cycles Stephan Schmidt <schst@php.net> Slide 13 of 39

Slide 15: PEAR Community PEAR Group 7 developers Quality Doc Website Developers Assurance Team Team Team • No strict hierarchy • All developers vote on important decisions • Mailinglists for all institutions – pear-dev@lists.php.net – pear-doc@lists.php.net – pear-qa@lists.php.net Stephan Schmidt <schst@php.net> Slide 15 of 39

Slide 16: PEAR Quality Assurance Ensures high quality of PEAR by enforcing several rules • Code must conform to coding standards – intuitive API – packages should be designed with extensibility in mind – visibility of properties and methods • No backward compatibility breaks allowed in the same major version • Unit tests and documentation are requirements • Improved code by peer review Stephan Schmidt <schst@php.net> Slide 16 of 39

Slide 18: The PEAR Installer • PEAR is installed by default since PHP4.3 • If not installed, use http://go-pear.org (interactive script that installs all required components) • Various frontends are available – Command Line Interface (default) – Webinterface – GTK Frontend • All frontends provide the same commands Stephan Schmidt <schst@php.net> Slide 18 of 39

Slide 19: PEAR Installer (CLI) Stephan Schmidt <schst@php.net> Slide 19 of 39

Slide 20: PEAR Installer (Web) Stephan Schmidt <schst@php.net> Slide 20 of 39

Slide 21: PEAR Installer Features • Downloads and installs PEAR packages and C Extensions • Creates packages that can be uploaded at the PEAR Website • Automatically checks dependencies on other packages, PHP version and PHP extensions • Only installs and upgrades packages of your preferred state (stable, beta, alpha, devel) • Can create and install third-party packages Stephan Schmidt <schst@php.net> Slide 21 of 39

Slide 22: PEAR Installer commands $ pear install <packagename> downloads and installs the package $ pear uninstall <packagename> uninstalls the package $ pear list lists all installed packages $ pear list-upgrades lists packages that have new versions $ pear config-show displays installer configuration …plus some more commands, mainly for developers Stephan Schmidt <schst@php.net> Slide 22 of 39

Slide 23: PEAR Installer internals • Uses XML-RPC to communicate with the PEAR Website • Downloads the tgz archive of a package • The package.xml file describes the content of the package as well as any dependencies on other packages • Extracts all needed files to your local PEAR installation folders and stores information in the PEAR registry • Currently being refactored by Greg Beaver Stephan Schmidt <schst@php.net> Slide 23 of 39

Slide 24: Shared Hosts • PEAR mostly not installed • No shell access Manual installation of PEAR • All packages contain standard PHP code • Download tar.gz from website • Unpack • Upload to shared host • Set include path (.htaccess or ini_set()) Stephan Schmidt <schst@php.net> Slide 24 of 39

Slide 25: PEAR Filesystem Structure • All files are stored in one directory on your server – Can be set using pear config-set (defaults to /usr/share/pear) – Should not be in your webroot – Add it to your include path • Classnames map to directory structure: – HTTP_Request class is in /usr/share/pear/HTTP/Request.php • Special folders for tests and docs: – /usr/share/pear/tests/XML_Parser/ – /usr/share/pear/docs/HTTP_Server Stephan Schmidt <schst@php.net> Slide 25 of 39

Slide 26: Using PEAR packages • Classes may be included by using <?PHP require_once 'HTTP/Request.php'; ?> • A lot of packages use a driver based architecture: <?PHP require_once 'DB.php'; $dbh = DB::connect('mysql://user:pass@host'); ?> • Unified error handling in all packages using PEAR_Error Stephan Schmidt <schst@php.net> Slide 26 of 39

Slide 27: PEAR error handling • Errors are instances of PEAR_Error that contain – Error message and optional code – function backtrace to help with debugging • Error handling can be set globally or for single instances – print the message – die on error – trigger PHP error – handle it using a callback • Will be replaced with PEAR_ErrorStack and/or exceptions in PHP5 Stephan Schmidt <schst@php.net> Slide 27 of 39

Slide 28: Example 1 - Database abstraction <?php require_once 'DB.php'; $db =&DB::connect('mysql://usr:pw@localhost/dbnam'); if (DB::isError($db)) { die($db->getMessage()); } $res =&$db->query('SELECT * FROM mytable'); while ($row = $res->fetchRow()) { echo $row[0] . \"\\n\"; } ?> Stephan Schmidt <schst@php.net> Slide 28 of 39

Slide 29: Example 1 - Database abstraction Advantages of using PEAR::DB • Easy switching between several database backends (currently 13 database types are supported) • Very intuitive to use • Errors can be checked with DB::isError( $foo ) • Improves compatibility between databases by lowercasing fieldnames, trimming return values, etc. • Emulates prepare/execute for databases that do not support this natively Stephan Schmidt <schst@php.net> Slide 29 of 39

Slide 30: Example 2 - Beautifying XML <root> <section title=\"This is an example\" id=\"myId\" author=\"Stephan Schmidt\"><para> Although this document is wellformed, it is <em type=\"strong\">not</em> looking very nice. </para> <para> But there's help, as PEAR::XML_Beautifier is able to beautify any valid XML document. </para></section> </root> Stephan Schmidt <schst@php.net> Slide 30 of 39

Slide 31: Example 2 - Beautifying XML <?PHP require_once 'XML/Beautifier.php'; $fmt = &new XML_Beautifier(); $result = $fmt->formatFile('example1.xml', 'result.xml'); if (PEAR::isError($result)) { echo $result->getMessage(); exit(); } ?> Stephan Schmidt <schst@php.net> Slide 31 of 39

Slide 32: Example 2 - Beautifying XML <root> <section author=\"Stephan Schmidt\" id=\"myId\" title=\"This is an example\"> <para> Although this document is wellformed, it is <em type=\"strong\">not</em> looking very nice. </para> <para>But there's help, as … valid XML document.</para> </section> </root> Stephan Schmidt <schst@php.net> Slide 32 of 39

Slide 33: Other interesting PEAR packages • phpDocumentor, a tool for generating API documentation from JavaDoc-style inline comments • SOAP, complete client and server SOAP library • PHPUnit, framework for Unit tests • Spreadsheet_Excel_Writer, excel spreadsheet generator without any need for external libraries • File_PDF, PDF generator without any need for external libraries • XML_Serializer, allround XML reader/writer Stephan Schmidt <schst@php.net> Slide 33 of 39

Slide 34: Who is using PEAR? • Horde (Framework) • TikiWiki (Wiki application) • S9Y (Weblog application) • Savant (Template engine) • Seagull PHP Framework (Framework) • patUser (PHP Application Tools) • YAWP (Application framework) • Yawiki (Wiki application) • A lot of commercial applications Stephan Schmidt <schst@php.net> Slide 34 of 39

Slide 35: Contributing to PEAR There are several ways to contribute: • By submitting bug reports or patches • By translating the documentation • By contributing to the documentation • By creating new packages Stephan Schmidt <schst@php.net> Slide 35 of 39

Slide 36: Including new packages • Make sure that the functionality is not in PEAR already • Make sure you follow the PEAR coding styles and naming standards • Make sourcecode, examples and docs available • Propose the package in PEPr • Discuss your proposal on pear-dev • Call for votes • Register your package • Upload release Stephan Schmidt <schst@php.net> Slide 36 of 39

Slide 37: Creating PEAR packages • Adjust \"package.xml\" Contains information about package, state, maintainer(s), dependencies, changelog and included files • PEAR_PackageFileManager will help you • Open a shell and move to the package folder • Run pear package • Test the resulting package • Upload it to pear.php.net Stephan Schmidt <schst@php.net> Slide 37 of 39

Slide 38: The Future of PEAR • Channel support – Allows you to distribute your own application using PEAR by providing a package server • Better support for PHP5 – Improved error handling – Interfaces – Exceptions • Improved Quality Assurance Stephan Schmidt <schst@php.net> Slide 38 of 39

Slide 39: Thank you! Thanks for your attention, feel free to ask any questions now. Links: • http://www.php-tools.net (the slides) • http://pear.php.net • http://pecl.php.net • schst@php.net Stephan Schmidt <schst@php.net> Slide 39 of 39

Slideshare.net (beta)