Skip to content

Commit

Permalink
Improve the readme / contribution
Browse files Browse the repository at this point in the history
  • Loading branch information
@pionl
pionl committed Mar 19, 2024
1 parent 42cc565 commit 2212c8e
Show file tree
Hide file tree
Showing 2 changed files with 71 additions and 69 deletions.
85 changes: 47 additions & 38 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
@@ -1,52 +1,57 @@
# Contribution or overriding
# Contribution Guidelines

Are welcome. To add a new provider just add a new Handler (which extends AbstractHandler). Then implement the chunk
upload and progress.
- [Pull Requests](#pull-requests)
- [Adding new library](#adding-new-library)
- [Your additions to your code base](#your-additions-to-your-code-base)

1. Fork the project.
2. Create your bugfix/feature branch and write your (try well-commented) code.
3. Commit your changes (and your tests) and push to your branch.
4. Create a new pull request against this package's `master` branch.
5. **Test your code in [laravel-chunk-upload-example](https://github.com/pionl/laravel-chunk-upload-example)**.
We welcome contributions to our project. If you want to add a new provider, follow these steps:

1. **Fork the Project:** Begin by forking the project to your own GitHub account.
2. **Create a Feature Branch:** Create a new branch for your bug fix or feature implementation. Ensure your code is well-commented.
3. **Commit and Push Changes:** Make your changes, including any necessary tests, and commit them to your branch. Then, push your changes to your forked repository.
4. **Submit a Pull Request:** Once your changes are ready, submit a pull request to merge them into the main project's `master` branch.
5. **Test Your Code:** Before submitting your pull request, ensure that your code works properly by testing it in the [laravel-chunk-upload-example](https://github.com/pionl/laravel-chunk-upload-example) project.
6. **Debugging Assistance:** If you encounter any issues, consider using XDEBUG for debugging purposes.

## Pull Requests

- **Use the [PSR-2 Coding Standard](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-2-coding-style-guide.md).**
The easiest way to apply the conventions is to use `composer run lint:fix`.
When submitting pull requests, please adhere to the following guidelines:

- **Coding Standards:** Follow the [PSR-2 Coding Standard](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-2-coding-style-guide.md). You can easily apply these conventions using `composer run lint:fix`.

- **Release Cycle:** Consider our release cycle, aiming to follow [SemVer v2.0.0](http://semver.org/).

- **Document Changes:** Document any changes in behavior thoroughly, ensuring that the `README.md` and other relevant documentation are updated accordingly.

- **Consider our release cycle.** We try to follow [SemVer v2.0.0](http://semver.org/).
- **Feature Branches:** Create feature branches for your pull requests rather than requesting to pull from your master branch directly.

- **Document any change in behaviour.** Make sure the `README.md` and any other relevant
documentation are kept up-to-date.
- **Single Feature per Pull Request:** Submit one pull request per feature. If you're implementing multiple features, send separate pull requests for each.

- **Create feature branches.** Don't ask us to pull from your master branch.
Before submitting your pull request:

- **One pull request per feature.** If you want to do more than one thing, send multiple pull requests.
1. **Rebase Changes:** Rebase your changes on the master branch to ensure a clean commit history.
2. **Lint Project:** Check for any coding standard violations using `composer run lint`.
3. **Run Tests:** Ensure that all tests pass by running `composer run test`.
4. **Write Tests (Recommended):** If possible, write tests to cover your code changes.
5. **Rebase Commits (Optional):** Consider rebasing your commits to keep them concise and relevant.

### Before pull-request do:
Thank you for your contributions!

1. Rebase your changes on master branch
2. Lint project `composer run lint`
3. Run tests `composer run test`
4. (recommended) Write tests
5. (optinal) Rebase your commits to fewer commits

**Thank you!**
# Adding new library

# Handler class
The basic handler `AbstractHandler` allows to implement own detection of the chunk mode and file naming. Stored in the Handler namespace but you can
store your handler at any namespace (you need to pass the class to the `FileReceiver` as a parameter)
The `AbstractHandler` class provides a foundation for implementing custom detection of chunk mode and file naming. While it's stored in the Handler namespace by default, you can place your handler in any namespace and pass the class to the `FileReceiver` as a parameter.

### You must implement:
### You Must Implement:

- `getChunkFileName()` - Returns the chunk file name for a storing the tmp file
- `isFirstChunk()` - Checks if the request has first chunk
- `isLastChunk()` - Checks if the current request has the last chunk
- `isChunkedUpload()` - Checks if the current request is chunked upload
- `getPercentageDone()` - Calculates the current uploaded percentage
- `getChunkFileName()`: Returns the chunk file name for storing the temporary file.
- `isFirstChunk()`: Checks if the request contains the first chunk.
- `isLastChunk()`: Checks if the current request contains the last chunk.
- `isChunkedUpload()`: Checks if the current request is a chunked upload.
- `getPercentageDone()`: Calculates the current upload percentage.

### Automatic detection
To enable your own detection, just overide the `canBeUsedForRequest` method
### Automatic Detection

To enable your own detection, simply override the `canBeUsedForRequest` method:

```php
public static function canBeUsedForRequest(Request $request)
Expand All @@ -55,8 +60,12 @@ public static function canBeUsedForRequest(Request $request)
}
```

# Fork
Edit the `HandlerFactory` and add your handler to the `$handlers` array
# Your additions to your code base

If you wish to contribute without forking, follow these steps:

1. **Edit HandlerFactory:** Add your handler to the `$handlers` array.

2. **Runtime Usage:** Call `HandlerFactory::register($name)` at runtime to register your custom Handler and utilize it.

# At runtime or without forking
Call the `HandlerFactory::register($name)` to register your own Handler at runtime and use it
Feel free to contribute and thank you for your support!
55 changes: 24 additions & 31 deletions readme.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,80 +8,73 @@

## Introduction

> Supports Laravel from 5.2 to 9 (covered by integration tests for 7/8/9 versions).
Laravel Chunk Upload simplifies chunked uploads with support for multiple JavaScript libraries atop Laravel's file upload system, designed with a minimal memory footprint. Features include cross-domain request support, automatic cleaning, and intuitive usage.

Easy to use service/library for chunked upload with supporting multiple JS libraries on top of Laravel's file upload with low memory footprint in mind.
For example repository with **integration tests**, visit [laravel-chunk-upload-example](https://github.com/pionl/laravel-chunk-upload-example).

Supports feature as [cross domains requests](https://github.com/pionl/laravel-chunk-upload/wiki/cross-domain-requests), automatic clean schedule and easy usage.

Example repository with **integration tests** can be found in [laravel-chunk-upload-example](https://github.com/pionl/laravel-chunk-upload-example).

> Before adding pull requests read CONTRIBUTION.md. Help me fix your bugs by debugging your issues using XDEBUG (and try to do a fix - it will help you become better).
Before contributing, familiarize yourself with the guidelines outlined in CONTRIBUTION.md.

## Installation

**1. Install via composer**
**1. Install via Composer**

```
```bash
composer require pion/laravel-chunk-upload
```

**2. Publish the config (Optional)**
**2. Publish the Configuration (Optional)**

```
```bash
php artisan vendor:publish --provider="Pion\Laravel\ChunkUpload\Providers\ChunkUploadServiceProvider"
```

## Usage

Setup consists of 3 steps:
The setup involves three steps:

1. Integrate your controller that will handle the file upload. [How to](https://github.com/pionl/laravel-chunk-upload/wiki/controller)
2. Set a route for the controller. [How to](https://github.com/pionl/laravel-chunk-upload/wiki/routing)
2. Choose your front-end provider below (we support multiple providers in single controller)
1. Integrate your controller to handle file uploads. [Instructions](https://github.com/pionl/laravel-chunk-upload/wiki/controller)
2. Define a route for the controller. [Instructions](https://github.com/pionl/laravel-chunk-upload/wiki/routing)
3. Select your preferred frontend provider (multiple providers are supported in a single controller).

| Library | Wiki | single & chunk upload | simultaneous uploads | In [example project](https://github.com/pionl/laravel-chunk-upload-example) | Author |
|---- |----|----|----| ---- | ---- |
| Library | Wiki | Single & Chunk Upload | Simultaneous Uploads | Included in [Example Project](https://github.com/pionl/laravel-chunk-upload-example) | Author |
|---------|------|-----------------------|----------------------|--------------------------------------------------|--------|
| [resumable.js](https://github.com/23/resumable.js) | [Wiki](https://github.com/pionl/laravel-chunk-upload/wiki/resumable-js) | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | [@pionl](https://github.com/pionl) |
| [DropZone](https://github.com/dropzone/dropzone) | [Wiki](https://github.com/pionl/laravel-chunk-upload/wiki/dropzone) | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | [@pionl](https://github.com/pionl) |
| [jQuery-File-Upload](https://github.com/blueimp/jQuery-File-Upload) | [Wiki](https://github.com/pionl/laravel-chunk-upload/wiki/jquery-file-upload) | :heavy_check_mark: | :heavy_multiplication_x: | :heavy_check_mark: | [@pionl](https://github.com/pionl) |
| [Plupload](https://github.com/moxiecode/plupload) | [Wiki](https://github.com/pionl/laravel-chunk-upload/wiki/plupload) | :heavy_check_mark: | :heavy_multiplication_x: | :heavy_multiplication_x: | [@pionl](https://github.com/pionl) |
| [simple uploader](https://github.com/simple-uploader) | :heavy_multiplication_x: | :heavy_check_mark: | :heavy_multiplication_x: | :heavy_multiplication_x: | [@dyktek](https://github.com/dyktek) |
| [ng-file-upload](https://github.com/danialfarid/ng-file-upload) | [Wiki](https://github.com/pionl/laravel-chunk-upload/wiki/ng-file-upload) | :heavy_check_mark: | :heavy_multiplication_x: | :heavy_multiplication_x: | [@L3o-pold](https://github.com/L3o-pold) |

**Simultaneous uploads:** The library must send last chunk as last, otherwise the merging will not work correctly.
**Simultaneous Uploads:** The library must send the last chunk as the final one to ensure correct merging.

**Custom disk:** At this moment I recommend using the basic storage setup (not linking public folder). It is not tested (Have free time to ensure it is working? PR the changes!).
**Custom Disk:** Currently, it's recommended to use the basic storage setup (not linking the public folder). If you have time to verify its functionality, please PR the changes!

For more detailed information (tips) use the [Wiki](https://github.com/pionl/laravel-chunk-upload/wiki) or for working example continue to separate repository with [example](https://github.com/pionl/laravel-chunk-upload-example).
For detailed information and tips, refer to the [Wiki](https://github.com/pionl/laravel-chunk-upload/wiki) or explore a working example in a separate repository with [example](https://github.com/pionl/laravel-chunk-upload-example).

## Changelog

Can be found in [releases](https://github.com/pionl/laravel-chunk-upload/releases).
View the changelog in [releases](https://github.com/pionl/laravel-chunk-upload/releases).

## Contribution or extending
## Contribution or Extension

> Read contribution before your PR (and use example repository to run integration tests).
Review the contribution guidelines before submitting your PRs (and utilize the example repository for running integration tests).

See [CONTRIBUTING.md](CONTRIBUTING.md) for how to contribute changes. All contributions are welcome.
Refer to [CONTRIBUTING.md](CONTRIBUTING.md) for contribution instructions. All contributions are welcome.

## Compatibility

> Laravel 5/6 should be still supported but we are not testing them via automation sccripts
Though not tested via automation scripts, Laravel 5/6 should still be supported.

| Version | PHP |
|---------|---------------|
| 11.* | 8.2 |
| 10.* | 8.1, 8.2 |
| 9.* | 8.0, 8.1 |
| 8.* | 7.4, 8.0, 8.1 |
| 7.* | 7.4 |



## Copyright and License

[laravel-chunk-upload](https://github.com/pionl/laravel-chunk-upload)
was written by [Martin Kluska](http://kluska.cz) and is released under the
[MIT License](LICENSE.md).
[laravel-chunk-upload](https://github.com/pionl/laravel-chunk-upload) was authored by [Martin Kluska](http://kluska.cz) and is released under the [MIT License](LICENSE.md).

Copyright (c) 2016 and beyond Martin Kluska
Copyright (c) 2017 and beyond Martin Kluska and all contributors (Thank you ❤️)

0 comments on commit 2212c8e

Please sign in to comment.