{"id":24475568,"url":"https://github.com/nassiry/filesize-handler","last_synced_at":"2025-05-07T06:06:36.536Z","repository":{"id":271431709,"uuid":"913425664","full_name":"nassiry/filesize-handler","owner":"nassiry","description":"The FileSizeHandler class is a utility designed to fetch and format file sizes across various file storage systems.","archived":false,"fork":false,"pushed_at":"2025-04-20T06:29:29.000Z","size":21,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-05-07T06:06:31.368Z","etag":null,"topics":["binary-file-size","binary-prefix","decimal-file-size","decimal-prefix","file-size-prefix","iec-file-size","php-amazon-file-size","php-file-size","php-ftp-file-size","si-file-size"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nassiry.png","metadata":{"files":{"readme":"README.md","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":"2025-01-07T16:55:38.000Z","updated_at":"2025-04-22T05:07:47.000Z","dependencies_parsed_at":null,"dependency_job_id":"2dc07a8a-ac55-4edd-82ce-a99c2955bc84","html_url":"https://github.com/nassiry/filesize-handler","commit_stats":null,"previous_names":["nassiry/filesize-handler"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nassiry%2Ffilesize-handler","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nassiry%2Ffilesize-handler/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nassiry%2Ffilesize-handler/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nassiry%2Ffilesize-handler/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nassiry","download_url":"https://codeload.github.com/nassiry/filesize-handler/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252823918,"owners_count":21809713,"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":["binary-file-size","binary-prefix","decimal-file-size","decimal-prefix","file-size-prefix","iec-file-size","php-amazon-file-size","php-file-size","php-ftp-file-size","si-file-size"],"created_at":"2025-01-21T09:15:15.718Z","updated_at":"2025-05-07T06:06:36.528Z","avatar_url":"https://github.com/nassiry.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# PHP FileSizeHandler\n\n![Packagist Downloads](https://img.shields.io/packagist/dt/nassiry/filesize-handler)\n![Packagist Version](https://img.shields.io/packagist/v/nassiry/filesize-handler)\n![PHP](https://img.shields.io/badge/PHP-%5E8.0-blue)\n![License](https://img.shields.io/github/license/nassiry/filesize-handler)\n\n\u003c/div\u003e\n\nThe `FileSizeHandler` class is a utility designed to fetch and format file sizes across various file storage systems. It offers cross-platform compatibility with support for both **SI (decimal)** and **IEC (binary)** standards, making it HDD-agnostic and highly flexible.\n- **Local Files**\n- **Remote Files (HTTP/HTTPS)** (via [Remote File Extension](https://github.com/nassiry/filesize-handler-remote-extension))\n- **FTP** (via [FTP Extension](https://github.com/nassiry/filesize-handler-ftp-extension))\n- **Amazon S3** (via [S3 Extension](https://github.com/nassiry/filesize-handler-s3-extension))\n- **Google Cloud Storage** (via [Google Cloud Extension](https://github.com/nassiry/filesize-handler-google-cloud-extension))\n- **Custom Sources** (via user-implemented interfaces)\n\nThis package addresses the discrepancies in file size measurement (binary vs decimal units) and provides flexible APIs for developers.\n\n### Features\n1. **Supports Local, Remote, and FTP Files:**\n    - Easily calculate file sizes from multiple sources.\n2. **Binary and Decimal Calculations:**\n    - Switch between binary (KiB, MiB, etc.) and decimal (KB, MB, etc.) bases with simple methods.\n3. **Fluent Interface:**\n    - Intuitive method chaining for base selection and size formatting.\n4. **Extensibility:**\n    - Ready for integration with cloud storage systems like S3 and Google Cloud.\n5. **i18n Support:**\n    - Format file size with custom localized units.\n    - Dynamically provide translations for units.\n6. **Chaining and Echo Support:**\n    - Supports method chaining for cleaner code.\n    - Directly `echo` the handler instance to get the formatted size.\n7. **Custom Source Support**:\n    - Implement `FileSourceInterface` and register your custom source.\n\n## Table Of Contents\n1. [Why Was This Class Created?](#why-was-this-class-created)\n2. [Useful Links](#useful-links)\n3. [Requirements](#requirements)\n4. [Installation](#installation)\n5. [Usage](#usage)\n    - [Local File](#local-file)\n    - [Extending the Library](#extending-the-library)\n6. [Binary vs Decimal Units](#binary-vs-decimal-units)\n    - [Switching Units](#switching-units)\n    - [Dynamic Locale and Unit Customization](#dynamic-locale-and-unit-customization)\n7. [API Reference](#api-reference)\n    - [Source Methods](#source-methods)\n    - [Configuration Methods](#configuration-methods)\n    - [Output Methods](#output-methods)\n8. [Extensions](#extensions)\n    - [Available Extensions](#available-extensions)\n9. [Contributing](#contributing)\n10. [License](#license)\n\n### Why Was This Class Created?\nWhen working with file sizes, differences in measurement units across systems can cause confusion:\n- **Cross-OS Consistency**: File size interpretations vary between operating systems (Windows, Linux, macOS) and hardware (HDD/SSD manufacturers often use decimal, while OS file systems may use binary).\n- **Unified Interface**: Simplifies handling file size retrieval from diverse sources.\n- **Extensibility**: Easily extend functionality by integrating additional storage systems via a simple, well-defined interface.\n\n\n#### Useful Links\n1. [Wikipedia: Binary Prefixes](https://en.wikipedia.org/wiki/Binary_prefix?utm_source=filesize-handler)\n    - Comprehensive explanation of binary (KiB, MiB) vs. decimal (KB, MB) prefixes.\n2. [NIST: Prefixes for Binary Multiples](https://physics.nist.gov/cuu/Units/binary.html?utm_source=filesize-handler)\n    - Official standards for binary-based units.\n3. [IBM: Units of Measurement for Storage Data](https://www.ibm.com/docs/en/storage-insights?topic=overview-units-measurement-storage-data)\n    - Insights into storage measurement across platforms.\n4. [Google: Byte Units](https://developers.google.com/style/units-of-measure#byte-units)\n    - Guidelines for using decimal and binary units consistently.\n5. [Metric View: What are binary prefixes?](https://metricviews.uk/2024/02/18/what-are-binary-prefixes/?utm_source=filesize-handler)\n    - Provides an overview of binary prefixes and their usage\n\n    \n### Requirements\n- **PHP**: Version 8.0 or higher\n- **PHP Extension** - `ext-intl`: Required\n\n## Installation\nThe recommended way use Composer to install the package:\n\n```bash\ncomposer require nassiry/filesize-handler\n```\n### Usage\n### Local File\nBy default, the library supports fetching file sizes for local files.\n```php\nuse Nassiry\\FileSizeUtility\\FileSizeHandler;\n\n$handler = FileSizeHandler::create()\n    -\u003elocal('/path/to/file')\n    -\u003ebinary();\n\n// Get the formatted size\necho $handler-\u003eformat(); // Example output: \"1.23 MiB\"\n\n// Or use directly with echo\necho FileSizeHandler::create()\n    -\u003elocal('/path/to/file')\n    -\u003ebinary()\n    -\u003eformat();\n```\n\n### Extending the Library\nTo add support for a new file source, implement the `FileSourceInterface`:\n```php\nuse Nassiry\\FileSizeUtility\\Sources\\FileSourceInterface;\n\nclass CustomCloudSource implements FileSourceInterface\n{\n    public function __construct(private string $apiKey, private string $filePath) {}\n\n    public function getSizeInBytes(): int\n    {\n        // Implement API logic to get file size\n        return 123456789;\n    }\n}\n\n$customSource = new CustomCloudSource('api-key', '/path/to/file');\n\n// Once implemented, register your custom source using:\n$handler = FileSizeHandler::create()\n    -\u003efrom($customSource)\n    -\u003ebinary();\n    \necho $handler-\u003eformat(); // Example output: \"1.23 MiB\"\n```\n\u003e For more information on extending the library, check the [official extensions](#available-extensions) available.\n\n## Binary vs Decimal Units\n### Switching Units\n```php\n$handler = FileSizeHandler::create()\n    -\u003elocal('/path/to/file.txt');\n\n// Default: Binary (1024-based)\necho $handler-\u003eformat(); // Output: \"1.23 MiB\"\n\n// Switch to Decimal (1000-based)\necho $handler-\u003edecimal()-\u003eformat(); // Output: \"1.30 MB\"\n```\n\n### Dynamic Locale and Unit Customization\n\n```php\n$customUnits = [\n    'binary_units' =\u003e ['o', 'Kio', 'Mio', 'Gio', 'Tio', 'Pio', 'Eio', 'Zio', 'Yio'],\n    'decimal_units' =\u003e ['o', 'Ko', 'Mo', 'Go', 'To', 'Po', 'Eo', 'Zo', 'Yo'],\n];\n\n$handler = FileSizeHandler::create('fr_FR', $customUnits)\n    -\u003elocal('/path/to/file')\n    -\u003ebinary();\n\necho $handler-\u003eformat(1); // Example output: \"1,2 Mio\"\n```\n#### Key Points:\nTwo-letter country codes are based on the [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) standard and are used in locale naming conventions.\n\n- **Examples of Supported Locales**: `en_US`, `fr_FR`, `de_DE`.\n- **The Default**: units and locale are set to `en_US`\n\n## API Reference\n\n#### `FileSizeHandler::create(string $locale = 'en_US', array $units = [])`\nInitializes a new `FileSizeHandler` instance.\n\n#### Source Methods\n- `local(string $filePath): self`  \n  Creates an instance for a local file.\n\n- `from(FileSourceInterface $source): self`  \n  Allows integration of a custom file source by implementing the `FileSourceInterface`.\n\n#### Configuration Methods\n- `binary(): self`  \n  Switches unit calculation to binary (1024-based).\n\n- `decimal(): self`  \n  Switches unit calculation to decimal (1000-based).\n  \n#### Output Methods\n\n- `bytes(): int`  \n  Returns the file size in bytes.\n\n- `format(int $precision = 2): string`  \n  Returns the formatted file size with the specified precision.\n\n### Extensions\n\n`FileSizeHandler` is extensible via optional extensions for advanced integrations. These extensions add support for remote and cloud-based file sources. Install the extensions via Composer.\n\n#### Available Extensions:\n\n| Extension      | Description                                     | Installation Command                                               | Documentation     |\n|----------------|-------------------------------------------------|-------------------------------------------------------------------|--------------------|\n| **FTP**        | Support for FTP file size retrieval.           | `composer require nassiry/filesize-handler-ftp-extension`        |  [See Full Documentation](https://github.com/nassiry/filesize-handler-ftp-extension) |\n| **Amazon S3**  | Fetch file sizes from Amazon S3 buckets.       | `composer require nassiry/filesize-handler-s3-extension`         |  [See Full Documentation](https://github.com/nassiry/filesize-handler-s3-extension) |\n| **Google Cloud** | Retrieve file sizes from Google Cloud Storage. | `composer require nassiry/filesize-handler-googlecloud-extension` |  [See Full Documentation](https://github.com/nassiry/filesize-handler-google-cloud-extension) |\n| **Remote**     | Support for files accessible via HTTP/HTTPS.   | `composer require nassiry/filesize-handler-remote-extension`     |  [See Full Documentation](https://github.com/nassiry/filesize-handler-remote-extension) |\n\n\n### Contributing\nFeel free to submit issues or pull requests to improve the package. Contributions are welcome!\n\n\n### Changelog\n\nSee [CHANGELOG](CHANGELOG.md) for release details.\n\n#### ⚠️ Deprecated Methods\n\nAs of version 1.1.0, the following methods are deprecated and will be removed in version 2.0.0:\n\n| Deprecated        | Use Instead |\n|------------------|-------------|\n| `baseBinary()`    | `binary()`  |\n| `baseDecimal()`   | `decimal()` |\n| `formattedSize()` | `format()`  |\n| `sizeInBytes()`   | `bytes()`   |\n\n### License\nThis package is open-source software licensed under the [MIT license](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnassiry%2Ffilesize-handler","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnassiry%2Ffilesize-handler","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnassiry%2Ffilesize-handler/lists"}