Updates

.editorconfig

@@ -0,0 +1,17 @@
+# For more information about the properties used in this file,
+# please see the EditorConfig documentation:
+# http://editorconfig.org
+
+[*]
+charset = utf-8
+end_of_line = lf
+indent_size = 4
+indent_style = space
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[{*.yml,package.json}]
+indent_size = 2
+
+# The indent size used in the package.json file cannot be changed:
+# https://github.com/npm/npm/pull/3180#issuecomment-16336516

.scrutinizer.yml

@@ -0,0 +1,69 @@
+inherit: true
+
+checks:
+  php:
+    verify_property_names: true
+    verify_argument_usable_as_reference: true
+    verify_access_scope_valid: true
+    useless_calls: true
+    use_statement_alias_conflict: true
+    variable_existence: true
+    unused_variables: true
+    unused_properties: true
+    unused_parameters: true
+    unused_methods: true
+    unreachable_code: true
+    too_many_arguments: true
+    sql_injection_vulnerabilities: true
+    simplify_boolean_return: true
+    side_effects_or_types: true
+    security_vulnerabilities: true
+    return_doc_comments: true
+    return_doc_comment_if_not_inferrable: true
+    require_scope_for_properties: true
+    require_scope_for_methods: true
+    require_php_tag_first: true
+    psr2_switch_declaration: true
+    psr2_class_declaration: true
+    property_assignments: true
+    prefer_while_loop_over_for_loop: true
+    precedence_mistakes: true
+    precedence_in_conditions: true
+    phpunit_assertions: true
+    php5_style_constructor: true
+    parse_doc_comments: true
+    parameter_non_unique: true
+    parameter_doc_comments: true
+    param_doc_comment_if_not_inferrable: true
+    optional_parameters_at_the_end: true
+    one_class_per_file: true
+    no_unnecessary_if: true
+    no_trailing_whitespace: true
+    no_property_on_interface: true
+    no_non_implemented_abstract_methods: true
+    no_error_suppression: true
+    no_duplicate_arguments: true
+    no_commented_out_code: true
+    newline_at_end_of_file: true
+    missing_arguments: true
+    method_calls_on_non_object: true
+    instanceof_class_exists: true
+    foreach_traversable: true
+    fix_line_ending: true
+    fix_doc_comments: true
+    duplication: true
+    deprecated_code_usage: true
+    deadlock_detection_in_loops: true
+    code_rating: true
+    closure_use_not_conflicting: true
+    catch_class_exists: true
+    blank_line_after_namespace_declaration: false
+    avoid_multiple_statements_on_same_line: true
+    avoid_duplicate_types: true
+    avoid_conflicting_incrementers: true
+    avoid_closing_tag: true
+    assignment_of_null_return: true
+    argument_type_checks: true
+
+filter:
+  paths: [code/*, tests/*]

LICENSE

@@ -0,0 +1,17 @@
+Copyright (c) 2016, Bigfork Ltd - www.bigfork.co.uk
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+    * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+    * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the 
+      documentation and/or other materials provided with the distribution.
+    * Neither the name of Bigfork nor the names of its contributors may be used to endorse or promote products derived from this software 
+      without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE 
+LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE 
+GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 
+STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY 
+OF SUCH DAMAGE.

README.md

@@ -0,0 +1,126 @@
+# SilverStripe OAuth
+
+SilverStripe OAuth2 authentication, based on the PHP League's [OAuth2 client](http://oauth2-client.thephpleague.com/).
+
+### What this module does
+This module includes the base functionality for fetching access tokens and associating them with members. It provides methods for creating requests to OAuth providers, fetching access tokens with varyious scopes/permissions, and storing them in the database.
+
+### What this module doesn’t do
+
+This module does not provide “Log in with <provider>” buttons, “Fetch contacts from <provider>” buttons, or any other functionality for actually interacting with providers - it only fetches and stores tokens that will allow you to do that. It’s up to you to install the appropriate ppackages for third-party providers, and to implement functionality that makes use of the access tokens to fetch data from those providers.
+
+If you’re looking for “Log in with <provider>” functionality, take a look at the add-on for this module: [SilverStripe OAuth Login](https://github.com/bigfork/silverstripe-oauth2-login).
+
+## Installation
+
+This module must be installed with composer. Run `composer require bigfork/silverstripe-oauth:*` from the command line, and then run a `dev/build`.
+
+## Configuration
+
+Providers are configured using SilverStripe’s YAML configuration, mapping an “internal” name (passed around in URLs and stored in the database) to a PHP class that’s an instance of the PHP League’s `League\OAuth2\Client\Provider\AbstractProvider` class.
+
+Each provider can have a `constructor_options` array that will be passed to the constructor for the given provider class.
+
+For example, to setup Facebook as a provider, first install the [Facebook OAuth2 package](https://github.com/thephpleague/oauth2-facebook), and then add the following to your YAML config:
+
+```yml
+Bigfork\SilverStripeOAuth\Client\Factory\ProviderFactory:
+  providers:
+    'Facebook': # "Internal" name
+      class: 'League\OAuth2\Client\Provider\Facebook' # PHP class name
+      constructor_options: # Array to be passed as 1st arg to League\OAuth2\Client\Provider\Facebook::__construct()
+        clientId: '12345678987654321'
+        clientSecret: 'geisjgoesingoi3h1521onnro12rin'
+        graphApiVersion: 'v2.6'
+```
+
+---
+
+## Concepts
+
+### Models
+
+This module adds two new models:
+
+#### `OAuthAccessToken`
+
+A single OAuth access token, belonging to a `Member`. Fields include:
+
+- `Token` - the access token itself
+- `Provider` - the provider name (“internal” name - see [Configuration](#configuration))
+- `RefreshToken` - the refresh token (optional)
+- `Expires` - the token expiry date (optional)
+- `ResourceOwnerID` - the resource owner ID (optional)
+
+This model also has a `many_many` relation to [`OAuthScope`](#OAuthScope).
+
+#### `OAuthScope`
+
+A scope (or “permission”) that a token has. This is simply a one-column table (`Name`) that stores a list of scopes that _all_ providers may share. Note that scopes in this table are not unique to each provider (for example, Facebook 'email' and Google 'email' scopes will share the same database record).
+
+Has a `belongs_many_many` relation to [`OAuthAccessToken`](#OAuthAccessToken).
+
+### Controller
+
+The module includes one extra controller, `Bigfork\SilverStripeOAuth\Client\Control\Controller`. This controller is responsible for setting up authentication requests, redirecting users to the third-party providers, and checking/handling tokens & redirections when the user returns to the site from the provider.
+
+### Helper
+
+A simple class to help build an authentication request URL to create an access token.
+
+---
+
+## Usage
+
+Below are a few examples of how to perform common actions with fetching/using tokens:
+
+### Check whether a user's token has the given permission
+
+```php
+$member = Member::currentUser();
+$facebookToken = $member->AccessTokens()->filter(['Provider', 'Facebook'])->first();
+if (!$facebookToken->includesScope('user_friends')) {
+    echo 'Unable to access friends list';
+}
+```
+
+### Request an access token
+
+```php
+use Bigfork\SilverStripeOAuth\Client\Helper\Helper;
+
+// Build a URL for fetching a Facebook access token with the 'email' and 'user_friends' permissions
+// Will return a URL like: http://mysite.com/oauth/authenticate/?provider=Facebook&scope%5B0%5D=email&scope%5B2%5D=user_friends
+$url = Helper::buildAuthorisationUrl('Facebook', ['email', 'user_friends']);
+echo "<a href=" . $url . ">Connect to Facebook</a>";
+```
+
+### Check whether a token is expired
+```php
+$member = Member::currentUser();
+$facebookToken = $member->AccessTokens()->filter(['Provider', 'Facebook'])->first();
+if ($facebookToken->isExpired()) {
+    echo 'Oh no, the Facebook token has expired!';
+}
+```
+
+### Refresh an access token
+
+```php
+$member = Member::currentUser();
+$facebookToken = $member->AccessTokens()->filter(['Provider', 'Facebook'])->first();
+if ($facebookToken->isExpired()) {
+    $facebookToken->refresh();
+    echo 'Token refreshed successfully';
+}
+```
+
+---
+
+## Todo
+
+- Unit tests!
+- Investigate swapping `class` and `constructor_options` to instead be a service registered via `Injector`. Currently this is limited by the fact that we need to override the constructor arguments to add a `redirectUri` key to the first argument to `League\OAuth2\Client\Provider\AbstractProvider::__construct()`
+- Add in support for the `$collaborators` argument for `League\OAuth2\Client\Provider\AbstractProvider::__construct()`. This may depend on the outcome of the above item
+- Make the default behaviour of only allowing one access token per provider on each member optional, or just remove it
+- Better passing-around of redirect Uris, it's currently a bit messy

composer.json

@@ -1,10 +1,22 @@
 {
 	"name": "bigfork/silverstripe-oauth",
-	"description": "All the socials.",
+	"type": "silverstripe-module",
+	"description": "SilverStripe OAuth2 authentication, based on the PHP League's OAuth2 client",
+	"keywords": ["silverstripe", "oauth", "oauth2", "authentication"],
+	"authors": [
+		{
+			"name": "Loz Calver",
+			"email": "[email protected]"
+		}
+	],
+	"license": "BSD-3-Clause",
 	"require": {
         "silverstripe/framework": "^3.3",
         "league/oauth2-client": "^1.4"
 	},
+	"require-dev": {
+		"phpunit/phpunit": "~3.7@stable"
+	},
 	"autoload": {
 		"psr-4": {"Bigfork\\SilverStripeOAuth\\Client\\": "src/"}
 	}