WP Bucket

A lightweight wordpress plugin that helps you to login to your site by using a "Login by Bitbucket" system and it enables developers to run most of server side ability in plugin or theme by using of Bitbucket API, This includes access to all features of the version 1 and version 2 Bitbucket API .

So a developer can to create wordpress plugins or themes using of a simple php class named WP_Bucket and Bitbucket API.

This plugin created based on OAuth class and wp_remote_request function.

Installation

1. Download the latest version of WP Bucket, or copy it to local by git clone https://bitbucket.org/khosroblog/wp_bucket.git.
2. Unzip file and rename the folder to wp_bucket ( if it is a zip file ).
3. Move the wp_bucket folder into your wp-content/plugins directory.
4. Navigate to the Plugins dashboard page.
5. Activate the plugin WP Bucket.

WP Bucket Introduction using vimeo on the 20 minute.

http://vimeo.com/user4640255/wp-bucket-introduction

How to use that?

1. Settings

At first, you should set WP Bucket plugin.

# Create a Bitbucket Application

WP Bucket use a Bitbucket Application that play third person role in combining wordpress with Bitbucket instead of use a username and password. do as following image for creating Bitbucket Application

# WP Bucket setting in wordpress admin panel

Now, you can enter the token keys in previous section in specified field and save the settings.

# Bitbucket user Authenticate by "Login by Bitbucket" button

Usually you don't need authentication for getting public data and just use username. for example below code get public repository of user ezvijst.

.

<?php 
global $WP_Bucket;

$WP_Bucket->config(array(
    "oauth_token"        => null,
    "oauth_token_secret" => null
));

$WP_Bucket->api("2.0/repositories/evzijst");
?>

But you need to authenticate user for getting private repository or request of POST, DELETE, PUT type. for user authentication you should use "login by bitbucket" button in WP Bucket plugin.

You can to display "Login by Bitbucket" button in theme or plugin by using wb_login_button function and users can be authenticated by WP Bucket plugin with pushing this button, then you can accessed to private repositories. Also there is a test page that you can to use it in the plugin as an example.

.

.

// wp-bucket-test page URL
http://yoursite.com/wp-bucket-test/

// absolute path to wp-bucket-test.php file
wp-content/plugins/wp_bucket/pages/wp-bucket-test.php

Permission to the login-by-bitbucket and wp-bucket-test pages will be adjustable in wordpress admin panel, at default just administrator can use this pages.

2. Coding

# Global variable $WP_Bucket

You can access to all property and methods of classes WP_Bucket and WP_REST_OAuth by global variable $WP_Bucket in anywhere the theme or plugin or even in wordpress hooks.

# config method

you can configure WP_Bucket class with config method .this method give an argument that is an array or string like most of other wordpress functions. approximately most of parameters don't need any reconfiguration and be don't worry. except wp_user_id parameter that can be important for you.

At default WP_Bucket class for current user configured, but you can set class for an another user by set the parameter wp_user_id. for example:

.

<?php 
global $WP_Bucket;
$WP_Bucket->config("wp_user_id=3");
?>

Also you can have more control on your functions without using global variable and by create a copy of WP_Bucket class. for example:

.

<?php 
$my_class = new WP_Bucket("wp_user_id=3");
$my_class->api("url-to-api");
?>

# api method

This method is the most useful method of WP_Bucket class, the main usability of this method is for making REST request to the bitbucket website. return value of this method can be include one of JSON, XML, YAML, WP_Error outputs. at default if there"s no error, return value will be a JSON string. this method include 3 arguments.

Arguments

$url (string) (required)

a relative or absolute URL to the bitbucket API, also can be included some templates. for example:

.

<?php 
$user_name = "khosro";
// using relative URL
$WP_Bucket->api("2.0/users/$user_name");


// using absolute URL
$WP_Bucket->api("https://Bitbucket.org/!api/2.0/users/$user_name");

// using templates and relative URL
$WP_Bucket->api("2.0/users/{user_name}", "GET", array(
   "template"   =>  array(
                            "user_name" =>  $user_name
                        )
));
?>

$method (string) (optional)

A method that determine type of request to the bitbucket website that can be one of PUT, GET, POST, DELETE methods.

$params (array) (optional)

Array of parameters include template, body, query_params.

.

<?php 
$WP_Bucket->api("url-to-api", "GET", array(
    "query_params"  =>  array(), // string | array
    "body"          =>  array(), // json string | array
    "template"      =>  array() // array
));
?>

--- $query_params (string | array) (optional)

Array of variables for adding to the main signature url.

.

<?php 
$WP_Bucket->api("url-to-api", "GET", array(
    "query_params" =>   array("format" => "xml"), // or "format=xml"
));
?>

--- $body (json string | string | array) (optional)

Adding body to the POST or PUT requests. input values can be JSON or Array.

.

<?php 
$repo_slug = "my-repo-slug";
$user_name = "khosro";
$WP_Bucket->api("2.0/repositories/$user_name/$repo_slug", "POST", array(
    "body" =>   array(
                "description"   =>  "description for my-repo-slug",
                "language"  =>  "php"
            ), 
));
?>

--- $template (string | array) (optional)

An array of values for used templates in URL. a used template in URL should be in {} and just underscore, numbers and alphabets will be accessible.

.

<?php
$WP_Bucket->api("2.0/repositories/{user_name}/{my_repo}", "GET", array(
    "template"  =>  array(
                        "user_name" =>  "khosro",
                        "my_repo"   =>  "my-repo-slug"
                    ), 

));
?>

# download_stream method

Using this method you can download public or private projects from bitbucket.this method gives 3 arguments.

Arguments:

$repo_slug (string) (required)

A repository name that is exists in bitbucket and you want to download that.

$owner (string) (optional)

A username that is exists in bitbucket. if you skip that current username will be used.

$revision (string) (optional)

A SHA1 value for commit. also you can determine a branch , bookmark or tag name for that. if no value entered ,method will be use of master branch. output of this method will be in zip format.

.

<?php
// using a commit ID
$WP_Bucket->download_stream("my_repo_slug", "my_username", "3caa76e23677c78d6");

// using a tag name
$WP_Bucket->download_stream("my_repo_slug", "my_username", "v0.1.0");

// using a branch name
$WP_Bucket->download_stream("my_repo_slug", "my_username", "master");
?>

Created wordpress plugins by WP Bucket

List of created WP Bucket plugins will be shown in this part.

Support and error reporting:

What Bitbucket Issue Tracker? Use the issue tracker

You can to use this link for support and error reporting.

1. https://bitbucket.org/khosroblog/wp_bucket/issues

More documents for bitbucket API:

You can to learn more about bitbucket API by documents given in bitbucket website:

1. Use the Bitbucket REST APIs
2. OAuth on Bitbucket
3. Bitbucket API Version 1
4. Bitbucket API Version 2
5. REST API Browser

Special thanks to Mohammad Reza Golestan for fluent persian to english translation