{"id":26892168,"url":"https://github.com/hossein-zare/wester-chunk-upload","last_synced_at":"2025-05-12T14:11:44.765Z","repository":{"id":57080099,"uuid":"293240673","full_name":"hossein-zare/wester-chunk-upload","owner":"hossein-zare","description":"Wester chunk upload is a php library to handle chunked uploads which supports local and ftp file upload out of the box. You'll feel safe with the built-in file validator.","archived":false,"fork":false,"pushed_at":"2024-11-19T06:18:31.000Z","size":103,"stargazers_count":16,"open_issues_count":1,"forks_count":6,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-05-12T14:11:43.595Z","etag":null,"topics":["chunk","chunked-uploads","php","resumable","resumable-blobs","resumable-upload","upload"],"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/hossein-zare.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,"zenodo":null}},"created_at":"2020-09-06T09:08:32.000Z","updated_at":"2025-01-24T08:14:23.000Z","dependencies_parsed_at":"2023-02-13T23:45:23.341Z","dependency_job_id":"7be99253-cfbc-4a20-b1db-3b032690492b","html_url":"https://github.com/hossein-zare/wester-chunk-upload","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hossein-zare%2Fwester-chunk-upload","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hossein-zare%2Fwester-chunk-upload/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hossein-zare%2Fwester-chunk-upload/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hossein-zare%2Fwester-chunk-upload/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hossein-zare","download_url":"https://codeload.github.com/hossein-zare/wester-chunk-upload/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253754219,"owners_count":21958842,"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":["chunk","chunked-uploads","php","resumable","resumable-blobs","resumable-upload","upload"],"created_at":"2025-03-31T22:49:22.155Z","updated_at":"2025-05-12T14:11:44.716Z","avatar_url":"https://github.com/hossein-zare.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Wester Chunk Upload Library For PHP\nWester chunk upload is a php library to handle chunked uploads which supports local and ftp file upload out of the box.  \nYou'll feel safe with the built-in file validator.\n\n## Table of contents\n* [Installation](#installation)\n* [Basic Usage](#basic-usage)\n* [Drivers](#drivers)\n    * [Implement The Driver](#implement-the-driver)\n* [Methods](#methods)\n* [Properties](#properties)\n* [Validation Rules](#validation-rules)\n* [Language](#language)\n* [Flags](#flags)\n* [HTTP Response Status Codes](#http-response-status-codes)\n* [Client Side](#client-side)\n    * [Headers](#headers)\n    * [Examples](#examples)\n        * [Javascript](#javascript)\n        * [Contribution](#contribution)\n* [Support Us](#support-us)\n\n## Installation\n```bash\ncomposer require wester/chunk-upload\n```\n\n## Basic Usage\nHere's an example of the package.\n```php\n// You don't need this line in laravel or some other frameworks.\nrequire(\"./vendor/autoload.php\");\n\nuse Wester\\ChunkUpload\\Chunk;\nuse Wester\\ChunkUpload\\Validation\\Exceptions\\ValidationException;\n\ntry {\n    $chunk = new Chunk([\n        'name' =\u003e 'video', // same as    $_FILES['video']\n        'chunk_size' =\u003e 4000, // must be equal to the value specified on the client side\n\n        // Driver\n        'driver' =\u003e 'local', // [local, ftp]\n\n        // Local driver details\n        'local_driver' =\u003e [\n            'path' =\u003e __DIR__ . '/uploads/', // where to upload the final file\n            'tmp_path' =\u003e __DIR__ . '/uploads/temp/', // where to store the temp chunks\n        ],\n\n        // FTP driver details\n        'ftp_driver' =\u003e [\n            'server' =\u003e '',\n            'username' =\u003e '',\n            'password' =\u003e '',\n\n            'path' =\u003e  '/uploads/', // where to upload the final file\n            'tmp_path' =\u003e '/uploads/temp/', // where to store the temp chunks\n        ],\n\n        // File details\n        'file_name' =\u003e Chunk::RANDOM_FILE_NAME,\n        'file_extension' =\u003e Chunk::ORIGINAL_FILE_EXTENSION,\n\n        // File validation\n        'validation' =\u003e ['extension:mp4,avi'],\n    ]);\n\n    $chunk-\u003evalidate()-\u003estore();\n\n    if ($chunk-\u003eisLast()) {\n\n        // done\n        $chunk-\u003egetFilePath();\n        \n    } else {\n        $chunk-\u003eresponse()-\u003ejson([\n            'progress' =\u003e $chunk-\u003egetProgress()\n        ]);\n    }\n\n} catch (ValidationException $e) {\n    $e-\u003eresponse(422)-\u003ejson([\n        'message' =\u003e $e-\u003egetMessage(),\n        'data' =\u003e $e-\u003egetErrors(),\n    ]);\n} catch (\\Exception $e) {\n    $e-\u003eresponse(400)-\u003eabort();\n}\n```\n\n## Drivers\nThis package supports `ftp` file upload out of the box.  \n`local` and `ftp` or custom drivers can be used.\n\n```php\n'driver' =\u003e 'ftp',\n```\n\n* ### Implement The Driver\n    Your custom driver should implement the `\\Wester\\ChunkUpload\\Drivers\\Contracts\\DriverInterface`.  \n\n    ```php\n    'driver' =\u003e \\My\\Custom\\Drivers\\DriverName::class,\n    'custom_driver' =\u003e [\n        'path' =\u003e  '/uploads/',\n        'tmp_path' =\u003e '/uploads/temp/',\n    ],\n    ```\n\n    ```php\n    \u003c?php\n\n    namespace My\\Custom\\Drivers;\n\n    class DriverName implements \\Wester\\ChunkUpload\\Drivers\\Contracts\\DriverInterface\n    {\n        public function open() {};\n        public function close() {};\n        public function store($fileName) {};\n        public function delete() {};\n        public function move() {};\n        public function increase() {};\n        public function prevExists() {};\n        public function exists() {};\n    }\n    ```\n\n## Methods\n* `store()` stores the chunk and merges it.\n* `validate()` validates the chunk.\n* `getFilePath()` gets the final file path.\n* `getProgress()` gets the progress percentage (float).\n* `isLast()` checks if its the last chunk.\n* `getFileExtension()` gets the file extension.\n* `getFileName()` gets the file name without extension.\n* `getFullFileName()` gets the full file name with extension.\n* `getTempFilePath()` gets the temp file path.\n* `getSize()` gets the current chunk size.\n* `getTotalNumber()` gets the total number of chunks.\n* `setLanguage([...])` sets the language to the provided array\n* `response($status = null)` returns an instance of `\\Wester\\ChunkUpload\\Response`\n\n    ```php\n    $chunk-\u003eresponse(200)-\u003ejson([...]);\n    $chunk-\u003eresponse()-\u003ejson([...]);\n\n    // If an exception is caught...\n    $e-\u003eresponse(400)-\u003e...\n    $e-\u003eresponse(400)-\u003eabort();\n    $e-\u003eresponse()-\u003eabort(400);\n    ...\n    ```\n\n## Properties\n* `configs` returns an array of the parsed configs.\n\n    ```php\n    $chunk-\u003econfigs['name'];\n    ...\n    ```\n* `header` returns an instance of `\\Wester\\ChunkUpload\\Header`\n\n    ```php\n    $chunk-\u003eheader-\u003echunkNumber;\n    $chunk-\u003eheader-\u003echunkTotalNumber;\n    $chunk-\u003eheader-\u003echunkSize; // equal to: x-chunk-size \n    $chunk-\u003eheader-\u003efileName;\n    $chunk-\u003eheader-\u003efileSize;\n    $chunk-\u003eheader-\u003efileIdentity;\n    ```\n\n## Validation Rules\n* `extension`\n    ```php\n    'validation' =\u003e ['extension:mp4,avi']\n    ```\n* `size`\n    ```php\n    'validation' =\u003e ['size:237492']\n    ```\n\n * `min`\n    ```php\n    'validation' =\u003e ['min:10000']\n    ```\n\n* `max`\n    ```php\n    'validation' =\u003e ['max:90000']\n    ```\n\n## Language\nYou can easily change the validation messages the same as Laravel.\n\n```php\n$chunk-\u003esetLanguage([\n    'min' =\u003e [\n        'numeric' =\u003e 'The :attribute must be at least :min.',\n        'file' =\u003e 'The :attribute must be at least :min kilobytes.',\n    ],\n    'max' =\u003e [\n        'numeric' =\u003e 'The :attribute may not be greater than :max.',\n        'file' =\u003e 'The :attribute may not be greater than :max kilobytes.',\n    ],\n    'size' =\u003e [\n        'numeric' =\u003e 'The :attribute must be :size.',\n        'file' =\u003e 'The :attribute must be :size kilobytes.',\n    ],\n    'mimes' =\u003e 'The :attribute must be a file of type: :values.',\n\n    'attributes' =\u003e [\n        'x-file-name' =\u003e 'file',\n        'x-file-size' =\u003e 'file',\n    ],\n]);\n```\n\n## Flags\n* `Chunk::RANDOM_FILE_NAME` creates a random file name.\n* `Chunk::ORIGINAL_FILE_NAME` preserves the original file name.\n* `Chunk::ORIGINAL_FILE_EXTENSION` preserves the original file extension.\n\u003e You can also specify a custom file name and extension.\n\n## HTTP Response Status Codes\nThis package uses the HTTP response status codes to decide what to do next if the request fails or succeeds when uploading.\n\n* ### Success\n    * `200` All of the chunks have been uploaded completely.\n    * `201` The server is waiting for the next chunk to be sent.\n\n* ### Errors\n    The following status codes will interrupt the process.\n\n    * `400`\n    * `404`\n    * `415`\n    * `422`\n    * `500`\n    * `501`\n\n\u003e Feel free to add more status codes to your client side.\n\n\u003e If another status code is returned the chunk must be re-uploaded such as `timeout` and `network error`.\n\n## Client Side\n### Headers\nThere are some headers that should be sent to the server.\n* `x-chunk-number` The current chunk number which is being uploaded.\n* `x-chunk-total-number` The total number of chunks.\n* `x-chunk-size` Maximum size of each chunk. (each chunk must be 4000 bytes and only the last chunk can be less than that)\n* `x-file-name` The uploaded file name.\n* `x-file-size` The uploaded file size.\n* `x-file-identity` Random string for the file which must be 32 characters in length.\n\nAn example of the headers.\n```json\n{\n    \"x-chunk-number\" : 1,\n    \"x-chunk-total-number\" : 5,\n    \"x-chunk-size\" : 4000,\n    \"x-file-name\" : \"my-file-name.mp4\",\n    \"x-file-size\" : 20000,\n    \"x-file-identity\" : \"rmghdygvdstcsjglltmbvkynxpeajgcg\"\n}\n```\n\n### Examples \u0026 Packages\nYou can find examples in [wester-chunk-upload-examples](https://github.com/hossein-zare/wester-chunk-upload-examples/) repository.\n\n#### **Javascript**\nThe client side implementation in Javascript.\n* [https://github.com/hossein-zare/wester-chunk-upload-examples/tree/master/javascript](https://github.com/hossein-zare/wester-chunk-upload-examples/tree/master/javascript)\n\n#### **React Native**\nThe client side implementation in React Native.\n* [https://github.com/hossein-zare/react-native-chunk-upload](https://github.com/hossein-zare/react-native-chunk-upload)\n\n#### Contribution\n* If you want to add more implementations in other languages please submit your PR to the [wester-chunk-upload-examples](https://github.com/hossein-zare/wester-chunk-upload-examples/) repository.\n\n## Support Us\nJust star the repository, that's it! 😉","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhossein-zare%2Fwester-chunk-upload","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhossein-zare%2Fwester-chunk-upload","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhossein-zare%2Fwester-chunk-upload/lists"}