Manual

Find out how much disk space is consumed by an installed pear package or a number of pear packages - analagous to the unix command df.

Summary

Features

investigate a single PEAR package.
investigate a set of PEAR packages.
display information for all installed packages.
output report in CSV format.
print sizes in human readable format.
specify what type of files are to be included in the report.
produce a summary report.
sort results by file size.
output results in XML format.

System Requirements

Mandatory resources:

PHP 5.1.4 or newer.
PEAR 1.4.0 or newer.
PEAR::Console_Getargs 1.3.4 or newer.
PEAR::Console_Table 1.1.0 or newer.
PEAR::HTML_Table 1.8.2 or newer.

About

Introduction

Introduction – About PEAR_Size

About PEAR_Size

PEAR_Size started as a php script that was born of a need to determine if there were any large pear packages installed that could be removed to free up space; it is analagous to the unix command df - this tool lists how much filespace each installed package consumes; also a subset of packages can be specified as can channels.

That script has evolved into a reusable set of classes that can be used from your own code and can render its report into HTML, XML, CSV and plain text formats. This is extensible so if required you could generate PDFs and possibly even charts of the data that is generated.

Re-using PEAR_Size

Re-using PEAR_Size – Embedding it in your own application

Re-using PEAR_Size

PEAR_Size consists of several core classes plus some ancillary ones. Most important is the PEAR_Size class itself. This performs the data-gathering process and then initiates the generation of the output report (using the analyse() and generateReport() methods respectively). The format of the report is set using the setOutputDriver() method.

If writing a command-line script that will utilise the power of PEAR_Size it is best to use the PEAR_Size_CLI class and run() for parsing the details and options set at the command prompt. The usage() method is for displaying either a usage screen or some error message. This method uses the application name as defined with the setAppName() method in those screens. If you intend to embed PEAR_Size into your own application or script you can set its name with the aforementioned method and retrieve it with appName().

Getting started

Overview

Overview – features and usage patterns

In brief

There are two ways in which you can use PEAR_Size: via the pear command line tool or integrated in a PHP script.

It's up to you to choose what is the best usage for you.

The Command-Line Script

The Command-Line Script – generating PEAR_Size reports at the commandline.

Switches and options

The pear size command can be used to generate reports.

  Usage: pear size [OPTIONS] [PACKAGE]
Display information on how much space an installed PEAR package required.

  -a, --all            display information for all installed packages
  -A, --allchannels    list packages from all channels, not just the default one
  -c, --channel        specify which channel
  -C, --csv            output results in CSV format (sizes are measured in bytes).
  -h, --human-readable print sizes in human readable format (for example: 492 B 1KB 7MB)
  -H, --si             likewise, but use powers of 1000 not 1024
  -t, --type           specify what type of files are required for the report
                       by default all types are assumed
  -s, --summarise      display channel summary view
  -S, --fsort          sort by file size
  -v, --verbose        display more detailed information
      --help           display this help and exit
  -V, --version        output version information and exit
  -X, --xml            output results in XML format
  -0, --killzero       do not output zero values in verbose mode

Types:
You can specify a subset of roles/file-types to be listed in the report.
These roles are those as supported by the PEAR installer.
These are: data, doc, ext, php, script, src, test

Examples:
                $ pear size --all
                $ pear size Console_Table
                $ pear size -ttest,doc Console_Table
                $ pear size --type=test,doc,php -h Console_Table Date_Holidays

Outputting Results

Outputting Results – The Output Drivers

Overview

PEAR_Size has a number of output drivers which provide a means of providing reports in a range of various formats in an extensible manner - they all extend the PEAR_Size_Output_Driver class.

Four drivers are currently available for use:

CSV, PEAR_Size_Output_CSV. Print a comma separate values of results.
HTML, PEAR_Size_Output_Html. Print reports in HTML.
Text, PEAR_Size_Output_Text. Prints the reports in pure text - no additional formatting.
XML, PEAR_Size_Output_XML. Prints the reports in XML.

If these drivers are not adequate for what you require, you should consider writing your own - based on the PEAR_Size_Output_Driver class.

Reference guide

Command-Line version

PEAR_Size_CLI::run

PEAR_Size_CLI::run() – Run the CLI version

Synopsis

require_once 'PEAR/Size/CLI.php';

integer PEAR_Size_CLI::run ( )

Description

Invokes PEAR_Size for command line scripts.

Return value

returns an integer

Throws

throws no exceptions thrown

Since

since version 0.1.2

Note

This function can not be called statically.

Output Drivers

Overview

Overview – The How and What of Output Drivers

In brief

Output drivers provide a means of presenting the same information in a variety of formats. The drivers that currently ship with PEAR_Size provide formatting for CVS, HTML, XML and plain text.

Below is an example of creating a driver for XML output:

<?php
$type = 'xml';
//get the factory
$factory = new PEAR_Size_OutputFactory();
//and create the driver...
$driver = $factory->createInstance($type);
?>

PEAR_Size_OutputFactory::createInstance

PEAR_Size_OutputFactory :: createInstance() – Create an Instance of an output driver.

Synopsis

require_once 'PEAR/Size/Factory.php';

integer PEAR_Size_OutputFactory::createInstance ( )

Description

Create an instance of an output driver.

Return value

returns instance of an Output Driver.

Throws

throws an exception if specified driver could not be found.

Since

since version 0.1.2

Note

This function can not be called statically.

PEAR_Size_Output_Driver::display

PEAR_Size_Output_Driver::display() – Display specified text

Synopsis

require_once 'PEAR/Size/Factory.php';

void PEAR_Size_Output_Driver::display ( string $text )

Description

Display text, formatted appropriately, according to the purpose of the driver.

Return value

returns void

Throws

throws no exceptions thrown

Since

since version 0.1.2

Note

This function can not be called statically.

This is a base class and should not be used directly.

PEAR_Size_Driver::generateReport

PEAR_Size_Driver::generateReport() – Generate Report

Synopsis

void PEAR_Size_Driver::generateReport ( array $channel_stats , array $search_roles , array $grand_total , array $display_params )

Description

Display text, formatted appropriately, according to the purpose of the driver.

Return value

returns void

Throws

throws no exceptions thrown

Since

since version 0.1.2

Note

This function can not be called statically.

This is a base class and should not be used directly.

PEAR_Size_Output_CSV::display

PEAR_Size_Output_CSV::display() – Display specified text

Synopsis

require_once 'PEAR/Size/Factory.php';

void PEAR_Size_Output_CSV::display ( string $text )

Description

Display text in CSV (comma separated) format.

Return value

returns void

Throws

throws no exceptions thrown

Since

since version 0.1.2

Note

This function can not be called statically.

PEAR_Size_Output_CSV::generateReport

PEAR_Size_Output_CSV::generateReport() – Generate CSV formatted report

Synopsis

void PEAR_Size_Output_CSV::generateReport ( array $channel_stats , array $search_roles , array $grand_total , array $display_params )

Description

Display text, formatted appropriately, according to the purpose of the driver.

Return value

returns void

Throws

throws no exceptions thrown

Since

since version 0.1.2

Note

This function can not be called statically.

PEAR_Size_Output_Html::display

PEAR_Size_Output_Html::display() – Display specified text

Synopsis

require_once 'PEAR/Size/Factory.php';

void PEAR_Size_Output_Html::display ( string $text )

Description

Display text in HTML format.

Return value

returns void

Throws

throws no exceptions thrown

Since

since version 0.1.2

Note

This function can not be called statically.

PEAR_Size_Output_Html::generateReport

PEAR_Size_Output_Html::generateReport() – Generate HTML formatted report

Synopsis

void PEAR_Size_Output_Html::generateReport ( array $channel_stats , array $search_roles , array $grand_total , array $display_params )

Description

Display report in HTML format.

Return value

returns void

Throws

throws no exceptions thrown

Since

since version 0.1.2

Note

This function can not be called statically.

PEAR_Size_Output_Text::display

PEAR_Size_Output_Text::display() – Display specified text

Synopsis

require_once 'PEAR/Size/Factory.php';

void PEAR_Size_Output_Text::display ( string $text )

Description

Display text in Text (comma separated) format.

Return value

returns void

Throws

throws no exceptions thrown

Since

since version 0.1.2

Note

This function can not be called statically.

PEAR_Size_Output_Text::generateReport

PEAR_Size_Output_Text::generateReport() – Generate plain text formatted report

Synopsis

void PEAR_Size_Output_Text::generateReport ( array $channel_stats , array $search_roles , array $grand_total , array $display_params )

Description

Display text, formatted appropriately, according to the purpose of the driver.

Return value

returns void

Throws

throws no exceptions thrown

Since

since version 0.1.2

Note

This function can not be called statically.

PEAR_Size_Output_XML::display

PEAR_Size_Output_XML::display() – Display specified text

Synopsis

require_once 'PEAR/Size/Factory.php';

void PEAR_Size_Output_XML::display ( string $text )

Description

Display text in XML format.

Return value

returns void

Throws

throws no exceptions thrown

Since

since version 0.1.2

Note

This function can not be called statically.

PEAR_Size_Output_XML::generateReport

PEAR_Size_Output_XML::generateReport() – Generate XML formatted report

Synopsis

void PEAR_Size_Output_XML::generateReport ( array $channel_stats , array $search_roles , array $grand_total , array $display_params )

Description

Display report in XML.

Return value

returns void

Throws

throws no exceptions thrown

Since

since version 0.1.2

Note

This function can not be called statically.