PDT/StudentsProgram2009/Phar

PHAR Support

What is phar?

The phar extension provides a way to put entire PHP applications into a single file called a "phar" (PHP Archive) for easy distribution and installation. Phar archives are best characterized as a convenient way to group several files into a single file. As such, a phar archive provides a way to distribute a complete PHP application in a single file and run it from that file without the need to extract it to disk. Additionally, phar archives can be executed by PHP as easily as any other file, both on the commandline and from a web server. Phar is kind of like a thumb drive for PHP applications.

Overview

The phar extenstion is added as built-in since php 5.3, Eclipse PDT should identify this file and provide capabilities to manage this files quickly with code navigation,exploration,export and import.

1. add internal and external to the phar includepath through UI Right click on a php project Properties->PHP Include Phar. You can add internal and external by click on the buttons Add PHARs… and Add Extenal PHARs respectively on the Libraries tab of the right of the window.And then you can remove them using Remove button.

2. extract phar(including zip based phar and tar based phar),and then navigate it.

And double click the php files in the phar can open it in the php editor.

3. support include grammar in php editor for files in phar

4. support code assist in php editor for files in phar

5. export phar(including zip based phar and tar based phar) Right click on a php project(src folder or folder) then click Export…then choose Phar Export under the PHP category,and then click next.

6. import phar(including zip based phar and tar based phar) And you also can import a phar to a php project. Right click on a php project(src folder or folder) then click Import …then choose Phar File under the PHP category,and then click next.

Implementation Detail

2. The following picture is the class diagram about extracting phar function.

Let us jump into the detail of how this function is implemented. DLTK does lots of the things.What we need to do is implement org.eclipse.dltk.core.IArchive and org.eclipse.dltk.core.IArchiveEntry interfaces,here are PharArchiveFile and PharArchiveEntry respectively,but both of them delegate a inner class to do the real work.When the user add a phar file to the include path of a php project, the constructor of class PharArchiveFile is called,and we the inner class PharFile is initialized, PharArchiveFile caches PharFile instance for later use.In the PharFile’s constructor we read(extract) the stub,then manifest and the file contents,finally the signature.There will be an exception if the phar file is corrupted.If the phar file is right organized,and then PharArchiveEntry instances are created which corresponding to the files in the phar file. PharArchiveEntry uses its inner class PharEntry to store the basic information of the file that in the phar,according to these information we can get the inputstream(used by DLTK) of the file,normally PharEntryBufferedRandomInputStream is used as the inputstream,but if that file is compressed BZ2PharEntryBufferedRandomInputStream or GZPharEntryBufferedRandomInputStream will be used.And then we need to do some little modification in method PHPExplorerContentProvider#getChildren:

if (parentElement instanceof ArchiveProjectFragment
				|| parentElement instanceof ArchiveFolder) {
	return super.getChildren(parentElement);
}

The code above delegate DLTK to retrieve the children. The ArchiveProjectFragment and ArchiveFolder are the conceptions of DLTK,ArchiveProjectFragment represents IArchive(here is PharArchiveFile).For ArchiveFolder,the files in a phar file are hierarchical,so ArchiveFolder is the connection between IArchive and IArchiveEntry.Above is for the pure phar file.But zip and tar based phar is the same,they use ZipArchiveFile and TarArchiveFile respectively.

2. The export function class diagram

From the wizard(org.eclipse.php.internal.ui.phar.wizard.PharPackageWizard). all the user input is collected into a PharPackage object.And then the PharPackage object is passed to class PharFileExportOperation’s constructor,and PharFileExportOperation delegate a IPharBuilder implementation(here is the only implementation,class PlainPharBuilder) to do the export work.In class PlainPharBuilder,it still call a IFileExporter implementation to do the real work.Here IFileExporter implementation could be PharFileExporter, TarFileExporter or ZipFileExporter,it depends on the PharPackage object from the export wizard.Here we will discuss the PharFileExporter mainly,because it is a little complicated when exporting a phar file(file that with a “phar” extension).According to the phar’s specification,the manifest contains all files’ information,when we export files,we must export one by one,so here problem occurs.It means that we could not write to a single outputstream continuously,or the phar format is wrong.So when exporting a phar we create several temp files,and finally write all the temp files to the main outputstream which write contents to the target file.

3. The import function class diagram

This function is the same as eclipse platform’s Archive file import function.And we use the same architecture as that function,and also because this we have less to do.The main entry is WizardPharFileResourceImportPage1,it depends on the user’s choose to initialize the structureProvider variable,use can choose phar,tar and zip,so structureProvider could be instance of PharLeveledStructureProvider,TarLeveledStructureProvider and ZipLeveledStructureProvider.In PharLeveledStructureProvider we use a inner PharFile to get the tree structure and the content inputstream of the file in the phar.And that is all,the base architecture will do the other things for us.

4. And the last is the unit test.The unit test is very simple,it only tests extracting phar with three conditions,phar with no compressed files in it,phar with zlib compressed files in it and phar with bzip compressed files in it.We know the files’ content than are in the phar in advance,so we compare the actually content to the content extracting from the phar,if the test fails,there must be something wrong about the extracting.The import function is based on extract function.Now I have not thought a good way to test the export function.But i think I will add this soon.