{"id":19311083,"url":"https://github.com/boxuk/describr","last_synced_at":"2025-04-22T14:30:27.061Z","repository":{"id":56951216,"uuid":"1893516","full_name":"boxuk/describr","owner":"boxuk","description":"So, tell me about your file... Given any file, PHP library describr will describe it","archived":false,"fork":false,"pushed_at":"2013-08-20T15:31:15.000Z","size":1786,"stargazers_count":7,"open_issues_count":0,"forks_count":2,"subscribers_count":10,"default_branch":"master","last_synced_at":"2025-04-02T00:35:13.882Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://www.boxuk.com/","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/boxuk.png","metadata":{"files":{"readme":"README.markdown","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2011-06-14T09:40:27.000Z","updated_at":"2024-01-10T10:17:50.000Z","dependencies_parsed_at":"2022-08-21T09:20:28.793Z","dependency_job_id":null,"html_url":"https://github.com/boxuk/describr","commit_stats":null,"previous_names":[],"tags_count":15,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/boxuk%2Fdescribr","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/boxuk%2Fdescribr/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/boxuk%2Fdescribr/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/boxuk%2Fdescribr/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/boxuk","download_url":"https://codeload.github.com/boxuk/describr/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250258737,"owners_count":21400960,"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-10T00:27:41.278Z","updated_at":"2025-04-22T14:30:26.077Z","avatar_url":"https://github.com/boxuk.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Describr\n\nDescribr is an object-oriented library for describing files. It uses a plugins to determine as much information\nas it can about a file.\n\nDescribr can be run from the command line via a supplied script, or it can\nbe integrated into any PHP project to gather information about a variety of\nfile types. You can write your own plugins, and a few of the file types Describr\nsupports \"out of the box\" with the bundled plugins include:\n\n * GIF\n * JPEG\n * PNG\n * WMV\n * MP4\n * MP3\n * AVI\n * ... and many more!\n\nIf there's a file you want to interrogate and its type isn't supported, you can add a plugin to {describr root}/lib/BoxUK/Describr/Plugins\nand it will automatically be picked up and ready for use!\n\n## Requirements:\n\n * PHP 5.3+\n * Fileinfo extension\n\nPlugins may have their own requirements. Some of the requirements for bundled\nplugins are:\n\n * GD extension - needed by the image file analysis plugin\n * [PHP-reader 1.8.1 or better](http://code.google.com/p/php-reader/ \"PHP-Reader version 1.8.1 or better\") - needed by the audio/video file analysis plugins\n * [Zend Framework](http://framework.zend.com/) - needed by PHP-Reader\n\n## Installation\n\nIt's easy to get Describring! If you just want to use it without writing plugins, you can install through our PEAR channel,\npear.boxuk.net (check our [Box UK Labs page](http://www.boxuk.com/labs/ \"Box UK Labs - Web experiments and prototypes\") for details on that),\nbut we're assuming that because you're here on our Github you want to get stuck in and grab the source. Great! Here's how you do it:\n\n 1. Install Zend Framework version 1.(latest). Probably best installed via PEAR so it's automatically on your PHP path,\n    else you'll need to add it to the path manually.\n 2. Download or checkout [PHP-reader 1.8.1 or better](http://code.google.com/p/php-reader/ \"PHP-Reader version 1.8.1 or better\")\n    and add it to your PHP include path.\n 3. Grab the source from [Github](https://github.com/boxuk/describr) by cloning the repo (or downloading the zip).\n\n### What if I can't add things to my php include path?\n\nIf, in stages (1) and (2), you weren't able to add Zend and PHP-Reader to your PHP include path, you can do the following:\n\nIn the root of Describr, copy {describr root}/lib/bootstrap.custom.php-sample to {describr root}/lib/bootstrap.custom.php. You'll now need to edit\n{describr root}/lib/bootstrap.custom.php and provide a path to PHP-Reader. You might also need to set a path to Zend Framework in\nthere too.\n\nIf you don't include the Zend Framework and PHP-Reader, Describr will still work but you will not be able to use it\nto get much information about audio/video files.\n\n## Using Describr\n\nIt's time to test that Describr is installed and ready to rock! We've provided a simple command line\nexecutable script to help you do this, so if you're on Linux/OSX/Unix, chmod {describr root}/bin/describr to be executable. On Windows,\nyou should just be able to run {describr root}/bin/describr.bat:\n\n```bash\ngavd@gavd-desktop:/opt/BoxUK/describr$ bin/describr\ndescribr - tell me about your file...\n(c) 2011 Box UK\nUsage: describr [path to file]\n       describr [path to file 1] [path to file 2] ... [path to file N]\n```\n\nIf you don't see the above, head back to the Installation section and see if there's anything you've missed. Failing\nthat, there's a Troubleshooting section below\n\nand then you should be able to do something like:\n\n```bash\ngavd@gavd-desktop:/opt/BoxUK/describr$ bin/describr tmp.txt\nAnalysing tmp.txt...\narray(2) {\n  [\"BoxUK\\General\"]=\u003e\n  array(6) {\n    [\"errors\"]=\u003e\n    array(0) {\n    }\n    [\"extension\"]=\u003e\n    string(3) \"txt\"\n    [\"type\"]=\u003e\n    string(8) \"document\"\n    [\"mimeType\"]=\u003e\n    string(10) \"text/plain\"\n    [\"fileSizeInBytes\"]=\u003e\n    int(4)\n    [\"fileSize\"]=\u003e\n    string(11) \"Extra Small\"\n  }\n  [\"BoxUK\\PlainText\"]=\u003e\n  array(4) {\n    [\"errors\"]=\u003e\n    array(0) {\n    }\n    [\"lines\"]=\u003e\n    int(1)\n    [\"characters\"]=\u003e\n    int(4)\n    [\"words\"]=\u003e\n    int(1)\n  }\n}\n```\n\nSo, we're up and running! Unless we're not, in which case:\n\n### Troubleshooting\n\nPlease check that:\n\n1. Make sure you've chmodded {describr}/bin/describr to be executable if you're on Linux/Unix/OSX:\n```bash\n    gavd@gavd-desktop:/opt/BoxUK/describr$ chmod u+x bin/describr\n```\n2. Zend Framework and PHP-Reader are both on the PHP include path OR you are using a custom bootstrap.php. In the latter\n   case, check that {describr root}lib/bootstrap.custom.php exists and $describr_pathToPHPReaderLibrary is set correctly. It must point to the\n   \"library\" or \"src\" directory (depending on the version of php-reader you're\n   using) - the one that contains the directory \"Zend\"\n3. Zend Framework should be installed. Installing this by PEAR is probably the\n   cleanest way to do this, but if you are not able to use PEAR (e.g. you're on\n   restrictive shared hosting, you can add the following to {describr root}/lib/bootstrap.custom.php:\n\n```php\n\u003c?php\n// ... add the line below to the end of the file\nset_include_path('.:/home/you/yourProject/lib/ZendFramework-1.11.1/library');\n```\n\nOf course, you will have to adjust the paths to point to where Zend is installed.\nThis is only as a last resort, it's better to use PEAR.\n\nAny other problems, please put in an issue on the Github project for Describr and we'll try to help you out. As much\ninfo as possible, please!\n\n## Plugins\n\nDescribr is based around plugins. Each plugin has a list of file types that it knows how to describe.\nThe built-in plugins live in {describr root}/lib/BoxUK/Describr/Plugins/BoxUK. Each\nplugin has one class that implements Plugin, mainly by extending AbstractPlugin.\n\n### Plugin dependencies\n\nYou specify the dependencies for each plugin in the plugin's code. Here's an example from ImagePlugin.php:\n\n```php\n/**\n * Make sure that this plugin has everything that it needs - i.e. GD\n *\n * @throws UnmetDependencyException If a dependency is not met\n */\npublic function checkDependencies() {\n    if (!extension_loaded('gd') || !function_exists('gd_info')) {\n        throw new UnmetDependencyException('GD is not installed');\n    }\n}\n```\n\nIf the dependencies of a plugin are not met (i.e. checkDependencies() fails), that plugin cannot be used, and will fail\nsilently and record an error when it finds a file it can match but can't report on because of missing dependencies:\n\n```bash\ngavd@gavd-desktop:/opt/BoxUK/describr$ bin/describr tests/resources/test.mov\nAnalysing tests/resources/test.mov...\narray(2) {\n  [\"BoxUK\\General\"]=\u003e\n    *removed for brevity*\n  [\"BoxUK\\AudioVideo\\Iso14496Video\"]=\u003e\n  array(1) {\n    [\"errors\"]=\u003e\n    array(1) {\n      [0]=\u003e\n      string(1236) \"This plugin matched the file tests/resources/test.mov, but the dependencies could not be matched. Details:\nexception 'BoxUK\\Describr\\Plugins\\UnmetDependencyException' with message 'Class Zend_Media_Iso14496 is not loaded - please ensure the php-reader library is on the include path if you wish to use this plugin' in /opt/BoxUK/describr/lib/BoxUK/Describr/Plugins/BoxUK/AudioVideo/Iso14496VideoPlugin.php:30\nStack trace: *removed for brevity*\n\n    }\n  }\n}\n```\n\n### Creating a plugin\n\nLet's create a trivial plugin. This plugin will just estimate the number of tags in an XML file by counting the \u003c\ncharacters and dividing by two - of course, you'd probably not do this in a production application but it should serve\nto illustrate Describr plugins!\n\nWe create a file {describr root}/lib/BoxUK/Describr/Plugins/Custom/XmlPlugin.php with the following contents:\n\n```php\n\u003c?php\n\nnamespace BoxUK\\Describr\\Plugins\\Custom;\n\n/**\n * Plugin for automatically describing XML files\n *\n * @package   BoxUK\\Describr\\Plugins\\BoxUK\n * @author    Box UK \u003copensource@boxuk.com\u003e\n * @copyright Copyright (c) 2011, Box UK\n * @license   http://opensource.org/licenses/mit-license.php MIT License and http://www.gnu.org/licenses/gpl.html GPL license\n * @link      http://github.com/boxuk/describr\n * @since     1.0.5\n */\nclass XmlPlugin extends \\BoxUK\\Describr\\Plugins\\AbstractPlugin\n{\n\n    /**\n     * @return array Types of file this plugin can determine information about\n     */\n    public function getMatchingMimeTypes() {\n        return array(\n            'text/xml'\n        );\n    }\n\n    /**\n     * @return array File extensions this plugin can determine information about.\n     * The \".\" is not included, so \"wmf\" is OK, \".wmf\" is not\n     */\n    public function getMatchingFileExtensions() {\n        return array(\n            'xml',\n            'xsl',\n        );\n    }\n\n    /**\n     * Stub out configuration loading\n     */\n    protected function loadConfiguration() {}\n\n    /**\n     * @return array With key 'tags' which is a count of tags in this document\n     */\n    protected function setAttributes() {\n        $fileContents = file_get_contents($this-\u003efullPathToFileOnDisk);\n        $tagOpenCount = substr_count($fileContents, '\u003c');\n        $tagCloseCount = substr_count($fileContents, '\u003c/');\n        $tagCount = $tagOpenCount - $tagCloseCount;\n\n        $this-\u003eattributes['tags'] = $tagCount;\n    }\n}\n```\n\nNotice we haven't specified any dependencies here - it's all vanilla PHP.\n\nNow, if we run our test script against Describr's own build.xml (for example), the XML plugin should automatically be used!\n\n```bash\ngavd@gavd-desktop:/opt/BoxUK/describr$ bin/describr build.xml\nAnalysing build.xml...\narray(3) {\n  [\"BoxUK\\General\"]=\u003e\n  array(5) {\n    [\"errors\"]=\u003e\n    array(0) {\n    }\n    [\"extension\"]=\u003e\n    string(3) \"xml\"\n    [\"type\"]=\u003e\n    NULL\n    [\"mimeType\"]=\u003e\n    string(15) \"application/xml\"\n    [\"fileSizeInBytes\"]=\u003e\n    int(1191)\n  }\n  [\"BoxUK\\PlainText\"]=\u003e\n  array(4) {\n    [\"errors\"]=\u003e\n    array(0) {\n    }\n    [\"lines\"]=\u003e\n    int(34)\n    [\"characters\"]=\u003e\n    int(1191)\n    [\"words\"]=\u003e\n    int(122)\n  }\n  [\"Custom\\Xml\"]=\u003e\n  array(2) {\n    [\"errors\"]=\u003e\n    array(0) {\n    }\n    [\"tags\"]=\u003e\n    int(15)\n  }\n}\n```\n\n## Accessing through your project\n\nUsing Describr on the command line is all well and good for getting going and testing plugins, but the meat of it is\nusing it in a project to tell you about files. You can do something like:\n\n```php\n\u003c?php\n// ...\n$this-\u003edescribr = new \\BoxUK\\Describr\\Facade();\n$responseFromDescribr = $this-\u003edescribr-\u003edescribeFile($pathToFile);\n```\n\nThis will give you a BoxUK\\Describr\\MediaFileAttributes object, which you can interrogate to find out which plugins said\nwhat about the file! The toArray method gives you what we've used so far in the command line scripts, or you can access\nit plugin-by-plugin for more fine-grained and powerful control.\n\n## Get involved!\n\nIf you find this project useful, or you've found a cool way of using it, let us know! If you've written any useful\nplugins, then by all means submit a pull request and we'll take a look!","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fboxuk%2Fdescribr","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fboxuk%2Fdescribr","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fboxuk%2Fdescribr/lists"}