{"id":20170799,"url":"https://github.com/pear/pear-core","last_synced_at":"2025-05-16T10:07:53.520Z","repository":{"id":1824792,"uuid":"2749065","full_name":"pear/pear-core","owner":"pear","description":"This is the definitive source of PEAR's core files.","archived":false,"fork":false,"pushed_at":"2024-11-24T22:10:38.000Z","size":18279,"stargazers_count":112,"open_issues_count":6,"forks_count":106,"subscribers_count":13,"default_branch":"master","last_synced_at":"2025-05-03T17:43:59.051Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://pear.php.net/package/PEAR","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"yathit/ydn-db","license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pear.png","metadata":{"files":{"readme":"README.CONTRIBUTING","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2011-11-10T14:39:32.000Z","updated_at":"2025-03-25T12:57:00.000Z","dependencies_parsed_at":"2024-01-15T20:21:41.424Z","dependency_job_id":"3ba4c699-0e63-4ad2-bb6c-699f9730f76c","html_url":"https://github.com/pear/pear-core","commit_stats":{"total_commits":5103,"total_committers":101,"mean_commits":"50.524752475247524","dds":0.459729570840682,"last_synced_commit":"ed08e2b2200980d9787211f81655f11f491d22dc"},"previous_names":[],"tags_count":117,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pear%2Fpear-core","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pear%2Fpear-core/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pear%2Fpear-core/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pear%2Fpear-core/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pear","download_url":"https://codeload.github.com/pear/pear-core/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253445623,"owners_count":21909829,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-14T01:21:17.277Z","updated_at":"2025-05-16T10:07:48.513Z","avatar_url":"https://github.com/pear.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"$Id$\n==CONTRIBUTING GUIDE FOR PEAR CORE DEVELOPERS==\nAuthor: Gregory Beaver \u003ccellog@php.net\u003e\n\nINTRODUCTION\n------------\n\nThank you for assisting in development of the premiere PHP installer!\nOver the years, certain protocols have developed for handling releases,\ndocumenting changes to the code, and coordinating efforts with the\nPHP core development team.\n\nThis document attempts to explain what it means to be a maintainer of\nthe PEAR package, and how to properly do maintenance.\n\nThis document assumes two things:\n\n1) you have already applied for a CVS account at http://www.php.net/cvs-php.php\n2) you have already applied for a PEAR account at http://pear.php.net/account-request.php\n\nFear not!  PEAR is slowly but surely evolving, and this document will hopefully only\nbecome smaller and simpler as this takes place.  Keep your fingers crossed!\n\nTable of Contents\n-----------------\n1. Fixing bugs/Adding features\n2. Writing regression tests\n3. Releasing PEAR\n4. synchronizing PEAR with the PHP release (PHP \u003e= 5.1.0)\n5. http://pear.php.net/go-pear and testing\n6. pear.php.net and rest\n\n1. FIXING BUGS/ADDING FEATURES\n------------------------------\n\nIn most cases, bugs or features are opened at the official bug tracker\nlocated at:\n\nhttp://pear.php.net/package/PEAR/bugs\n\nWhen you fix a bug, or implement feature requested, please follow this checklist:\n\n1) assign the bug to yourself in the bug tracker\n2) write a .phpt-based regression test that verifies the bug, or tests the\n   new feature.  The test should be written prior to any code changes, and\n   should attempt to work properly, but fail due to the bug in PEAR or non-existing\n   feature.  Please name the test after the bug tracker number to make it easier to\n   find.  If you fix bug #12345 name the test \"bug12345.phpt.\"  If the bug was in\n   the PEAR_Installer class, please save it in pear-core/tests/PEAR_Installer/bug12345.phpt\n3) fix the bug, or add the new feature.\n4) upgrade your local PEAR installation via \"pear upgrade -f package2.xml\"\n5) do a few simple tests to see if you have fixed the bug.  This should include\n   running the regression test that you wrote.  If the test is named bug12345.phpt,\n   use \"pear run-tests tests/PEAR_Installer/bug12345.phpt\" from the pear-core directory\n6) if the code did not fix the problem, go back to step 3 :)\n7) run the remaining regression tests to ensure that you did not break existing\n   features with your bugfix/feature addition.\n      cd tests\n      pear run-tests -rq\n   if any tests fail, examine the .out files (as in bug12345.out) to determine the cause\n   of failure.\n8) add an entry to the release notes in both package2.xml and package-PEAR.xml.\n   Please use the full bug summary as in:\n   * Fix Bug #12345: Foo failure in --packagingroot option [your pear username]\n9) Don't be afraid to ask the older developers for help or clarification!!\n\n2. WRITING REGRESSION TESTS\n---------------------------\n\nPEAR's regression tests are based on the versatile .phpt format, which is somewhat\ndocumented at:\n\n(official resource) http://qa.php.net/write-test.php\n(unofficial resource) http://weierophinney.net/matthew/archives/65-phpt-Tutorial.html\n\nIn addition to these fine and succinct tutorials, take a quick peek at the source\nof existing unit tests, such as those in pear-core/tests/PEAR_Installer/\n\nEach test in PEAR should make use of a simple principle: only display output when\nthere is an error.  This will allow simple cross-platform/cross-PHP version testing.\nIn addition, use the utility PEAR_PHPTest class found in tests/phpt_test.php.inc.\nThis will allow tremendous flexibility in testing.\n\nDon't be afraid to ask the older developers for help or clarification!\n\n3. RELEASING PEAR\n-----------------\n\nWhen releasing a new version of PEAR, follow these simple steps:\n\n1) set the release date in package2.xml and package-PEAR.xml to 1 week from the\n   current date.\n2) run this command:\n     pear package package2.xml package-PEAR.xml\n   and fix any errors\n3) upload the subsequent .tgz file (PEAR-1.4.6.tgz for PEAR version 1.4.6)\n   to a private location where others can download it\n4) post a message to the pear-qa@lists.php.net mailing list asking people to\n   install the package, and try to break it, by running all commands, and running\n   the unit tests\n5) if all goes well, release the package through http://pear.php.net/release-upload.php\n   on the release date in package2.xml.  ALWAYS RELEASE A PACKAGE THAT HAS BEEN\n   TESTED BY AT LEAST 1 INDEPENDENT SOURCE.  We've had too many broken releases\n   rushed out in the past.  If you're not sure, ask one of the older devs for help\n6) After another week, when it is clear that PEAR is working, you may need to coordinate\n   the release with PHP developers.\n\n4. SYNCHRONIZING PEAR WITH THE PHP RELEASE (PHP \u003e= 5.1.0)\n--------------------------------------------------------\n\nPHP 5.1.0 and newer make use of a new technology, the PHP archive, or \"phar\".\n\nThe UNIX build of PHP uses install-pear-nozlib.phar, and the windows build uses\ngo-pear.phar.  To create these files, follow these simple steps:\n\ncvs -d :pserver:yourcvs@cvs.php.net:/repository login [replace yourcvs with your login]\ncvs -d :pserver:yourcvs@cvs.php.net:/repository co pear-core\ncd pear-core/PEAR\nmkdir go-pear-tarballs\ncd go-pear-tarballs\npear download -Z PEAR-stable Archive_Tar-stable Console_Getopt-stable XML_Util-stable\ncd ../..\npear install --force PHP_Archive\nphp make-installpear-nozlib-phar.php\nphp make-gopear-phar.php\n\nNote that PHP 5.1 is required in order to create the archives, and they can be created\non either unix or windows.\n\nNow, these files need to reside in the document root of pear.php.net.  However, the\nfiles are stored in cvs at pear/installphars and are released as the package\npearweb_phars.\n\nAs such, you will need to ask someone with karma to commit them if you do not have karma,\nand to release the pearweb_phars package as well.\n\nTo use these files, do the following:\n\n1) UNIX\ncp install-pear-nozlib.phar /path/to/php-src/pear\ncd /path/to/php-src\nmake install-pear\n\n2) WINDOWS\nphp go-pear.phar\n\nThat's it!  In fact, the go-pear.bat that comes with PHP 5.1.x simply contains that line,\nso that people can simply type \"go-pear\" to install PEAR.  The code used to run go-pear.phar\nis located in pear-core/go-pear-phar.php.  This file ultimately loads\npear-core/PEAR/Start.php and pear-core/PEAR/Start/CLI.php.  These files are based off\nof the code in the web-based go-pear, which is discussed in the next section.\n\n5. HTTP://PEAR.PHP.NET/GO-PEAR AND TESTING\n---------------------------------\n\nOne of the most common methods used to install PEAR is http://pear.php.net/go-pear\n\ngo-pear is actually a file located in CVS at cvs.php.net in pearweb/public_html/go-pear\nand it contains, in a single PHP file, all of the code necessary to download PEAR and run\nit.  Unfortunately, this also makes it difficult to debug and to maintain, as there are\nmore than a few hacks to make it work within a single file.  However, it does the best\nit could under the circumstances, and contains code to install the CLI and the web-based\nfrontend, as well as to download the necessary packages.\n\nTesting this code is very difficult, and it is important to test on windows, and to\nfamiliarize yourself with related bugs that have been encountered (a search of\nhttp://www.beeblex.com is a good place to start).  If you are a brave and wonderful\nperson, and are willing to write ApacheTest-based tests for go-pear, we would\nenshrine you in the halls of glory for at least a year or so :).\n\nThe main thing to remember is that you need to be aware of how go-pear works, so\nthat you can be aware of its needs in relation to PEAR.\n\n6. PEAR.PHP.NET AND REST\n-------------------------------\n\nPerhaps the most complex aspect of maintaining the PEAR installer is the interaction\nwith pear.php.net.  The PEAR installer uses one protocols to access package information,\nREST (Representative State Transfer) to represent abstract meta-data about packages,\nand to respond to specific queries about this data.\nThere used to be support for XML-RPC (XML remote procedure call) in older version of PEAR\nbut got removed due to XML-RPC backends being obsoleted and not used anywhere.\n\nPEAR prior to version 1.4.0 exclusively uses XML-RPC, and specifically interacts with\nhttp://pear.php.net/xmlrpc.php, which is located at cvs.php.net in\npearweb/public_html/xmlrpc.php.  This file in turn accesses\npearweb/include/pear-database.php, which contains all of the specific functions used by\nthe PEAR installer.  pear-database.php contains a number of xml-rpc functions not used\nat all by the installer.  Fortunately, a complete list of functions used by the installer\nis documented in http://pear.php.net/channel.xml.\n\nREST is a description of a rather loose way of representing data, and can mean many things\nbut is most commonly distilled into \"Every resource has one unique URL for accessing and\nrepresenting this resource.\"  PEAR implements this using static XML files, located at\nhttp://pear.php.net/rest.  These files are auto-generated, and for more information on\nhow and what is generated, check the online manual, and the code at\npearweb/include/pear-rest.php.\n\nWhat is important to understand is that pear.php.net has had tremendous load issues\nrecently.  The largest URL accessed at pear.php.net is xmlrpc.php, which returns a\ntremendous amount of data.  Any changes to the PEAR installer can have a profound\neffect on the performance of pear.php.net.  REST is actually a major step forward because\nit distributes this load more effectively and eliminates all dynamic code processing,\nbut until PEAR 1.3.x disappears, xmlrpc will continue to be a noticeable load on the\nserver.  Consider all changes with care!\n\nTo implement a new feature or fix a bug, if you need to access some information\nremotely in a different way, always attempt to do this with the existing layout first.\nOnly add new REST as XML-RPC has bee phased out and the installer contains no such code.\n\nIf you plan to maintain the remote access portion of PEAR, it is imperative to\nbecome intimately familiar with how the website works.  Check out pearweb from\nCVS and study it, set up a local copy and take a day to make it work - this is no\nsmall endeavor, I assure you, but it is worth it for local testing.\n\nOnce you have a working local mirror, simply update your local channel.xml for PEAR\nwith a mirror and select that mirror.  Save this file as \"mychannel.xml\":\n\n\u003cchannel version=\"1.0\" xsi:schemaLocation=\"http://pear.php.net/channel-1.0 http://pear.php.net/dtd/channel-1.0.xsd\"\u003e\n\u003cname\u003epear.php.net\u003c/name\u003e\n\u003csuggestedalias\u003epear\u003c/suggestedalias\u003e\n\u003csummary\u003ePHP Extension and Application Repository\u003c/summary\u003e\n \u003cservers\u003e\n  \u003cprimary\u003e\n   \u003crest\u003e\n    \u003cbaseurl type=\"REST1.0\"\u003ehttp://pear.php.net/rest/\u003c/baseurl\u003e\n    \u003cbaseurl type=\"REST1.1\"\u003ehttp://pear.php.net/rest/\u003c/baseurl\u003e\n   \u003c/rest\u003e\n  \u003c/primary\u003e\n  \u003cmirror host=\"localhost\"\u003e \u003c!-- replace with the path to pearweb --\u003e\n   \u003crest\u003e\n    \u003cbaseurl type=\"REST1.0\"\u003ehttp://localhost/rest/\u003c/baseurl\u003e\n    \u003cbaseurl type=\"REST1.1\"\u003ehttp://localhost/rest/\u003c/baseurl\u003e\n   \u003c/rest\u003e\n  \u003c/mirror\u003e\n \u003c/servers\u003e\n\u003c/channel\u003e\n\nThen:\n\npear channel-update mychannel.xml\npear config-set preferred_mirror localhost\n\nThis will instruct the PEAR installer on your machine to access your local copy of pearweb\nas if it were the remote one.  This can be used to debug complex server interactions\nwithout requiring any internet access whatsoever.\n\nAgain, as with all other tasks, consult one of the experienced developers if you need\nassistance setting up pearweb locally, or have any questions!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpear%2Fpear-core","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpear%2Fpear-core","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpear%2Fpear-core/lists"}