Skip to content

Commit 9fa6812

Browse files
BlazOrazemBlazOrazem
committed
Initial commit
0 parents  commit 9fa6812

File tree

15 files changed

+510
-0
lines changed

15 files changed

+510
-0
lines changed

‎.github/workflows/linter.yml‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
---
2+
name: Linter
3+
4+
on:
5+
push:
6+
branches:
7+
- main
8+
pull_request:
9+
10+
jobs:
11+
linter:
12+
runs-on: ubuntu-latest
13+
name: Super-Linter
14+
steps:
15+
- name: Checkout changes
16+
uses: actions/checkout@v4
17+
with:
18+
fetch-depth: 0
19+
20+
- name: Run Super-Linter
21+
uses: github/super-linter@v4
22+
env:
23+
DEFAULT_BRANCH: main
24+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
25+
VALIDATE_YAML: true
26+
VALIDATE_JSON: true
27+
VALIDATE_MARKDOWN: true
28+
VALIDATE_PHP_BUILTIN: true

‎.github/workflows/tests.yml‎

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
---
2+
name: Tests
3+
4+
on:
5+
push:
6+
branches:
7+
- main
8+
pull_request:
9+
10+
jobs:
11+
phpUnitTests:
12+
runs-on: ubuntu-latest
13+
name: Unit Tests / PHP ${{ matrix.phpVersion }} / Winter ${{ matrix.winterRelease }}
14+
strategy:
15+
max-parallel: 6
16+
matrix:
17+
phpVersion: ['8.1', '8.2', '8.3']
18+
winterRelease: ['develop']
19+
winterReleaseDir: ['develop']
20+
fail-fast: false
21+
env:
22+
phpExtensions: mbstring, intl, gd, xml, sqlite
23+
cacheKey: ext-cache-v1
24+
winterCmsRelease: develop
25+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
26+
steps:
27+
- name: Checkout changes
28+
uses: actions/checkout@v4
29+
with:
30+
fetch-depth: 0
31+
32+
- name: Move files to a dropboxadapter-plugin directory
33+
run: mkdir dropboxadapter-plugin && find . -mindepth 1 -maxdepth 1 ! -name 'dropboxadapter-plugin' -exec mv -t dropboxadapter-plugin -- {} +
34+
35+
- name: Setup cache environment
36+
id: extcache
37+
uses: shivammathur/cache-extensions@v1
38+
with:
39+
php-version: ${{ matrix.phpVersion }}
40+
extensions: ${{ env.phpExtensions }}
41+
key: ${{ env.cacheKey }}
42+
43+
- name: Cache extensions
44+
uses: actions/cache@v4
45+
with:
46+
path: ${{ steps.extcache.outputs.dir }}
47+
key: ${{ steps.extcache.outputs.key }}
48+
restore-keys: ${{ steps.extcache.outputs.key }}
49+
50+
- name: Install PHP and extensions
51+
uses: shivammathur/setup-php@v2
52+
with:
53+
php-version: ${{ matrix.phpVersion }}
54+
extensions: ${{ env.phpExtensions }}
55+
56+
- name: Install Winter CMS
57+
run: |
58+
wget https://github.com/wintercms/winter/archive/${{ matrix.winterRelease }}.zip
59+
unzip ${{ matrix.winterRelease }}.zip
60+
rm ${{ matrix.winterRelease }}.zip
61+
shopt -s dotglob
62+
mv winter-${{ matrix.winterReleaseDir }}/* ./
63+
rmdir winter-${{ matrix.winterReleaseDir }}
64+
shopt -u dotglob
65+
cp config/cms.php config/testing/cms.php
66+
mkdir -p plugins/numencode
67+
mv dropboxadapter-plugin plugins/numencode/dropboxadapter
68+
69+
- name: Get Composer cache directory
70+
id: composercache
71+
run: echo "dir=$(composer config cache-files-dir)" >> $GITHUB_ENV
72+
73+
- name: Cache dependencies
74+
uses: actions/cache@v4
75+
with:
76+
path: ${{ env.dir }}
77+
key: ${{ runner.os }}-composer-${{ hashFiles('**/composer.json') }}
78+
restore-keys: ${{ runner.os }}-composer-
79+
80+
- name: Install Composer dependencies
81+
run: composer install --no-interaction --no-progress --no-suggest --prefer-dist
82+
83+
- name: Run unit tests
84+
run: php artisan winter:test -p NumenCode.DropboxAdapter --configuration=plugins/numencode/dropboxadapter/phpunit.xml

‎.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
.idea
2+
*.cache

‎.markdownlint.json‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
{
2+
"no-duplicate-heading": {
3+
"siblings_only": true
4+
}
5+
}

‎CHANGELOG.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# Changelog
2+
3+
All notable changes to this project will be documented in this file.
4+
5+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
6+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7+
8+
## [1.0.0] - 2025-07-08
9+
### Added
10+
- Initial release of the **DropboxAdapter Plugin**.
11+
- Laravel filesystem integration with the Dropbox v2 API.
12+
- Fully compatible with **Winter CMS v1.2.7** and **PHP 8.0+**.
13+
- Use case: enables Dropbox as a remote storage option for backups, sync operations, and custom filesystem logic.
14+
- Designed for integration with plugins like [`NumenCode.SyncOps`](https://github.com/numencode/wn-syncops-plugin).
15+
16+
### Notes
17+
- **Not compatible** with `media` or `uploads` disks in Winter CMS.
18+
- Intended for developer-oriented scenarios such as automation, deployment, or remote sync—not general file management.
19+
20+
---
21+
22+
### Links
23+
- GitHub repository: [wn-dropboxadapter-plugin](https://github.com/numencode/wn-dropboxadapter-plugin)

‎CONTRIBUTING.md‎

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
# Contributing
2+
3+
Contributions are **welcome** and will be fully **credited**.
4+
5+
Before creating an issue or pull request, please take a moment to read and understand this contribution guide.
6+
7+
---
8+
9+
## Etiquette
10+
11+
This project is open source, and the maintainers volunteer their time to build and maintain it. They provide the source code freely with the hope that it will be useful to others. Please be respectful and considerate when raising issues or submitting pull requests.
12+
13+
- **Be respectful**: Avoid abusive, angry, or impatient behavior toward maintainers or contributors.
14+
- **Stay constructive**: Provide detailed, actionable feedback and clearly describe issues or suggestions.
15+
- **Understand maintainers' decisions**: Contributions are accepted at the discretion of the maintainers. Respect their decision, even if your submission is not used.
16+
17+
Let’s show the world that developers are civilized, collaborative, and selfless!
18+
19+
---
20+
21+
## Viability
22+
23+
Before suggesting new features or changes, consider their viability:
24+
- Will the feature benefit other users of the project?
25+
- Is the feature aligned with the project's scope and goals?
26+
- Could the feature introduce unnecessary complexity or maintenance challenges?
27+
28+
Open source projects serve a diverse group of developers with varied needs, so your contributions should aim to add value to the broader community.
29+
30+
---
31+
32+
## Reporting Issues
33+
34+
Before filing an issue:
35+
1. **Attempt to replicate the problem** to rule out one-off incidents.
36+
2. **Search existing issues** to ensure your problem or suggestion hasn’t already been raised.
37+
3. **Check pull requests** for ongoing work that may address the issue.
38+
39+
---
40+
41+
## Submitting Pull Requests
42+
43+
When submitting a pull request:
44+
1. **Ensure the feature doesn’t already exist** in the codebase.
45+
2. **Review existing pull requests** to ensure no one else is working on the same feature or fix.
46+
3. Follow these best practices:
47+
- **One pull request per feature**: If you want to contribute multiple changes, submit separate pull requests for each.
48+
- **Provide a coherent commit history**: Squash intermediate commits into meaningful ones.
49+
- **Document your changes**: Update the `README.md` or other relevant documentation to reflect your changes.
50+
- **Adhere to coding standards**: Use the PSR-12 coding standard.
51+
52+
---
53+
54+
## Requirements
55+
56+
This project follows specific standards and guidelines to ensure consistency and maintainability:
57+
58+
1. **Coding Standard**
59+
- Follow **[PSR-12](https://www.php-fig.org/psr/psr-12/)**.
60+
- Use tools like [PHP Code Sniffer](http://pear.php.net/package/PHP_CodeSniffer) to check your code.
61+
62+
2. **Semantic Versioning**
63+
- This project adheres to **[SemVer v2.0.0](http://semver.org/)**.
64+
- Avoid making random or unnecessary breaking changes to public APIs.
65+
66+
3. **Documentation**
67+
- Document any changes in functionality.
68+
- Update all relevant files, including `README.md` and other documentation, as needed.
69+
70+
---
71+
72+
## Contribution Workflow
73+
74+
To contribute effectively:
75+
1. Fork the repository and create a new branch for your work.
76+
2. Ensure your branch is up-to-date with the `main` branch.
77+
3. Implement your feature or fix, ensuring compliance with the guidelines.
78+
4. Run tests and ensure no existing functionality is broken.
79+
5. Create a pull request with a clear description of the changes and why they are necessary.
80+
81+
---
82+
83+
**Thank you for contributing!** Your effort and time are greatly appreciated. Let’s build something amazing together.
84+
85+
**Happy coding**!

‎LICENSE.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
# MIT License
2+
3+
Copyright (c) 2025 NumenCode
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎Plugin.php‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
<?php namespace NumenCode\DropboxAdapter;
2+
3+
use System\Classes\PluginBase;
4+
use NumenCode\DropboxAdapter\Providers\DropboxServiceProvider;
5+
6+
class Plugin extends PluginBase
7+
{
8+
public function pluginDetails()
9+
{
10+
return [
11+
'name' => 'numencode.dropboxadapter::lang.plugin.name',
12+
'description' => 'numencode.dropboxadapter::lang.plugin.description',
13+
'author' => 'Blaz Orazem',
14+
'icon' => 'icon-dropbox',
15+
'homepage' => 'https://github.com/numencode/wn-dropboxadapter-plugin',
16+
];
17+
}
18+
19+
public function boot()
20+
{
21+
$this->app->register(DropboxServiceProvider::class);
22+
}
23+
}

‎README.md‎

Lines changed: 108 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,108 @@
1+
# Dropbox Adapter Plugin
2+
3+
The **Dropbox Adapter Plugin** provides Dropbox v2 API integration with Winter CMS as a custom filesystem disk driver.
4+
This allows limited usage of Dropbox with Laravel's Storage facade—primarily for custom logic and backup tools such as
5+
[`NumenCode.SyncOps`](https://github.com/numencode/wn-syncops-plugin).
6+
7+
[![Version](https://img.shields.io/github/v/release/numencode/wn-dropboxadapter-plugin?style=flat-square&color=0099FF)](https://github.com/numencode/wn-dropboxadapter-plugin/releases)
8+
[![Packagist PHP Version Support](https://img.shields.io/packagist/php-v/numencode/wn-dropboxadapter-plugin?style=flat-square&color=0099FF)](https://packagist.org/packages/numencode/wn-dropboxadapter-plugin)
9+
[![Checks](https://img.shields.io/github/check-runs/numencode/wn-dropboxadapter-plugin/main?style=flat-square)](https://github.com/numencode/wn-dropboxadapter-plugin/actions)
10+
[![Tests](https://img.shields.io/github/actions/workflow/status/numencode/wn-dropboxadapter-plugin/tests.yml?branch=main&label=tests&style=flat-square)](https://github.com/numencode/wn-dropboxadapter-plugin/actions)
11+
[![License](https://img.shields.io/github/license/numencode/wn-dropboxadapter-plugin?label=open%20source&style=flat-square&color=0099FF)](https://github.com/numencode/wn-dropboxadapter-plugin/blob/main/LICENSE.md)
12+
13+
---
14+
15+
## Target Audience
16+
17+
This plugin is designed for developers who want to interact with Dropbox from within Winter CMS using
18+
Laravel’s filesystem abstraction, especially for automation, remote syncing, and backup scenarios.
19+
20+
> **Note:** Due to framework limitations, Winter CMS (as of version 1.2) does not support using Dropbox as a
21+
> filesystem for core `media` or `uploads` disks. This plugin is not intended for direct media asset management,
22+
> but rather for use cases like backup transport, cloud storage sync, or custom plugin integration (e.g. [`NumenCode.SyncOps`](https://github.com/numencode/wn-syncops-plugin)).
23+
24+
## Installation
25+
26+
This plugin is available for installation via [Composer](http://getcomposer.org/).
27+
28+
```bash
29+
composer require numencode/wn-dropboxadapter-plugin
30+
```
31+
32+
Once the plugin is installed, ensure all migrations are executed:
33+
34+
```bash
35+
php artisan winter:up
36+
```
37+
38+
## Requirements
39+
40+
* [Winter CMS](https://wintercms.com/) version 1.2.7 or newer
41+
* PHP 8.0 or later
42+
* A Dropbox API access token
43+
44+
## Configuration
45+
46+
1. Create a Dropbox App in the [Dropbox App Console](https://www.dropbox.com/developers/apps) and generate an access token.
47+
2. Define a new filesystem disk in your `config/filesystems.php` file:
48+
```php
49+
'dropbox' => [
50+
'driver' => 'dropbox',
51+
'authorization_token' => env('DROPBOX_AUTH_TOKEN'),
52+
],
53+
```
54+
3. Add the token to your `.env` file:
55+
```dotenv
56+
DROPBOX_AUTH_TOKEN=your_generated_token
57+
```
58+
You can now interact with Dropbox programmatically using the Storage facade in Laravel:
59+
```php
60+
Storage::disk('dropbox')->put('backups/site.zip', $contents);
61+
```
62+
This is especially useful for custom automation (e.g., deployment scripts or remote backup workflows).
63+
64+
## Limitations
65+
- **Not compatible with Winter CMS native `media` or `uploads` disks.**
66+
- **Not suitable for asset serving or file uploading through the CMS backend UI.**
67+
68+
Use Dropbox through this plugin **only for custom filesystem operations** that are manually invoked or triggered
69+
via automation (e.g., within the [`NumenCode.SyncOps`](https://github.com/numencode/wn-syncops-plugin) plugin or similar).
70+
71+
## Example Use Case
72+
This plugin was created to support [`NumenCode.SyncOps`](https://github.com/numencode/wn-syncops-plugin),
73+
a Winter CMS plugin for managing deployments, backups, and environment synchronization. Dropbox serves as a
74+
remote storage destination for sync packages or archive backups.
75+
76+
---
77+
78+
## Changelog
79+
80+
All notable changes are documented in the [CHANGELOG](CHANGELOG.md).
81+
82+
---
83+
84+
## Contributing
85+
86+
Please refer to the [CONTRIBUTING](CONTRIBUTING.md) guide for details on contributing to this project.
87+
88+
---
89+
90+
## Security
91+
92+
If you identify any security issues, email info@numencode.com rather than using the issue tracker.
93+
94+
---
95+
96+
## Author
97+
98+
The **NumenCode.DropboxAdapter** plugin is created and maintained by [Blaz Orazem](https://orazem.si/).
99+
100+
For inquiries, contact: info@numencode.com
101+
102+
---
103+
104+
## License
105+
106+
This project is open-sourced software licensed under the [MIT license](https://opensource.org/licenses/MIT).
107+
108+
[![License](https://img.shields.io/github/license/numencode/wn-dropboxadapter-plugin?style=flat-square&color=0099FF)](https://github.com/numencode/wn-dropboxadapter-plugin/blob/main/LICENSE.md)

0 commit comments

Comments
 (0)