Skip to content
会計freee API の PHP SDKです。
PHP
Branch: master
Clone or download
Latest commit ee1ea44 Nov 11, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github/ISSUE_TEMPLATE Added documents and samples. Oct 28, 2019
.openapi-generator Update library code for Accounting freee API v0.0.6. Oct 28, 2019
docs Update library code for Accounting freee API v0.0.6. Oct 28, 2019
lib Updated version from v1.0.0-alpha to v1.0.0. Nov 11, 2019
samples Updated sample's composer. Oct 28, 2019
test Update library code for Accounting freee API v0.0.6. Oct 28, 2019
.openapi-generator-ignore Update library code for Accounting freee API v0.0.6. Oct 28, 2019
.php_cs Added library code. Oct 28, 2019
.travis.yml Added library code. Oct 28, 2019
CONTRIBUTION_GUIDE.md Added library code. Oct 28, 2019
LICENSE Added library code. Oct 28, 2019
README.md
README_auto-generated.md Updated version from v1.0.0-alpha to v1.0.0. Nov 11, 2019
composer.json Updated version from v1.0.0-alpha to v1.0.0. Nov 11, 2019
config.json Updated version from v1.0.0-alpha to v1.0.0. Nov 11, 2019
git_push.sh Update library code for Accounting freee API v0.0.6. Oct 28, 2019
phpunit.xml.dist Added library code. Oct 28, 2019

README.md

会計freee PHP SDK

会計freee API を PHP で利用するための SDK です。

会計freee API の詳細については、会計API 概要 | freee Developers Community をご参照ください。

目次

チュートリアル

会計freee PHP SDK を利用する手順について記載します。

前提条件

本SDKを利用する前に下記をご確認ください。

  • freee 本体のアカウントがあること
  • PHP の基礎について理解があること

freee 本体のアカウントは、後述する freeeアプリストアへのアプリケーション登録 で必要になります。

freee API に関しては、チュートリアルガイド をご参照ください。

PHP の基礎については、 PHP: PHP マニュアル - Manual をご参照ください。

実行環境

このリポジトリは以下の環境を想定しています。

  • PHP 7.1 以上
  • composer

このリポジトリは、 PHP 7.1 以上を対象としています。PHP の実行環境をお持ちでない方は、 PHP: インストールと設定 - Manual を参考に環境を準備してください。また、 composer はこちらからインストールしてください。

freeeアプリストアへのアプリケーション登録

本 SDK で利用する client_id および client_secret を取得するため、freeeアプリストアの開発者ページでアプリケーションを登録します。

こちらの チュートリアル | freee アプリストア を参考に、アプリケーションを登録して下さい。

本 SDK と接続するには、コールバックURLに、http://localhost:8000/auth-callback を設定します。

サンプルの実行方法

WebApp のサンプル

WebApp のサンプルの実行環境

サンプルは Laravel をベースに作成しています。サンプルを実行する際は、前述の実行環境に加え、下記も併せてご準備ください。

  • PHP 7.2 以上
    • BCMath PHP Extension
    • Ctype PHP Extension
    • JSON PHP Extension
    • Mbstring PHP Extension
    • OpenSSL PHP Extension
    • PDO PHP Extension
    • Tokenizer PHP Extension
    • XML PHP Extension
  • composer
  • Node.js (UI生成時に npm を使用するため)
WebApp のサンプルの実行環境 (Docker)

また、Docker を利用可能な方向けに、上記実行環境を含む Dockerfile および docker-compose.yaml を同梱しています。利用する際は、下記をご参考にご利用ください。

cd <本リポジトリのクローン先ディレクトリ>
cd samples
docker-compose build
docker-compose up -d
docker exec -it samples_webapp_1 /bin/bash

上記の操作後、dockerコンテナの /usr/src/app にログインできます。このディレクトリは、本リポジトリの samples/BasicWebApp をマウントしたものです。下記の手順を適宜読み替えて、ご利用ください。

WebApp のサンプルの実行手順

本リポジトリをクローンしたのち、PowerShell や bash などのターミナルでディレクトリに移動します。

cd <本リポジトリのクローン先ディレクトリ>
cd samples/BasicWebApp
cp .env.example .env

コピーした .env を開き、下記の部分を設定してください。 <client_id>, <client_secret> は、それぞれ freeeアプリストアへのアプリケーション登録 で取得した値を設定します。

FREEE_ACCOUNTING_CLIENT_ID=<client_id>
FREEE_ACCOUNTING_CLIENT_SECRET=<client_secret>

ターミナルで、下記を実行します。

# パッケージをインストールする
composer install

# Application encryption key を発行する
php artisan key:generate

# Laravel の内蔵サーバーを実行する
php artisan serve

# ※ Docker で動かしている場合は、下記のように host を指定する
php artisan serve --host 0.0.0.0

http://localhost:8000 を開き、ページが開けば正常に起動できています。

右上の「LOGIN」をクリックすると、freeeアプリストアのアプリケーションに対して認証が行われます。初回は「アプリ連携の開始」という画面が表示されますので、内容を確認し「許可する」ボタンをクリックしてください。

正常に認証されれば、 http://localhost:8000/home にリダイレクトされます。上部のバーに freee のユーザー名が表示されていれば成功です。また、ユーザー名を選択し、そのプルダウンから「Me」を選択すると、ユーザー情報や取引情報が表示されれば、情報を正しく取得できていることが確認できます。

なお、内蔵サーバーを停止するには、 Ctrl + c を押下します。

SDKの導入方法

この項では、本 SDK の導入の参考として、 Laravel で利用する方法を記述します。

まず、 Laravel のプロジェクトを新規作成します。既存のプロジェクトに導入する場合は、読み飛ばしてください。まず、Laravel のプロジェクトを作成するため、laravel コマンドを Installing Laravel を参考にインストールします。なお、前述の Dockerfile を利用する場合は、すでにインストール済みです。

# Laravel のプロジェクトを新規作成し、そのディレクトリに移動する
laravel new sampleapp
cd sampleapp

# 確認のため、Laravel の内蔵サーバーを実行する
php artisan serve

# ※ Docker で動かしている場合は、下記のように host を指定する
php artisan serve --host 0.0.0.0

# 内蔵サーバーを停止するには、 Ctrl + c を押下します

プロジェクトの準備ができたら、パッケージのインストールを行います。本SDK のコアである会計freee APIは OAuth2 による認証を行うため、 Laravel オフィシャルパッケージである Socialite も利用します。

  • freee/freee-accounting-sdk: 本SDK
  • socialiteproviders/generators: Socialite のカスタムプロバイダのベースコードを生成するためのパッケージ(参考: https://github.com/SocialiteProviders/Generators)
  • socialiteproviders/manager: Socialite のカスタムプロバイダを扱うためのパッケージ
composer require freee/freee-accounting-sdk
composer require socialiteproviders/generators
composer require socialiteproviders/manager

そして config/app.phpproviders に、下記を参考にプロバイダを追記します。

    'providers' => [
        // ... 中略 ...
        SocialiteProviders\Generators\GeneratorsServiceProvider::class,
        SocialiteProviders\Manager\ServiceProvider::class,
        // ... 中略 ...
    ],

socialiteproviders/generators の artisan コマンドを利用して、ベースコードを作成します。

# freee の OAuth2 認証を処理するコードを作成する
php artisan make:socialite FreeeAccounting --spec=oauth2 --authorize_url=https://accounts.secure.freee.co.jp/public_api/authorize --access_token_url=https://accounts.secure.freee.co.jp/public_api/token --user_details_url=https://api.freee.co.jp/api/1/users/me

# 作成したファイルを読み込む
composer dumpautoload

つぎに、認証用の画面を用意します。今回は laravel/ui を導入し、その画面を流用します。詳細は Authentication - Laravel - The PHP Framework For Web Artisans をご参照ください。

composer require laravel/ui --dev
php artisan ui vue --auth
npm install && npm run dev

この時点で、 routes/web.php には Auth::routes(); が追加され、認証周りのルーティングが設定されています。今回は、新規登録とパスワードリセットを利用しないので、下記のように編集します。

// Auth::routes();
Auth::routes([
    'register' => false,
    'reset' => false,
]);

これまでの操作で、Laravel の内部でユーザーデータを持つ認証機構のベースができました。しかし、会計freee APIでは、freee に認証・認可を問い合わせる造りになるため、さらに変更を加えます。

まず、 routes/web.php に下記のルーティングを追加します。

Route::get('login', 'Auth\LoginController@redirectToProvider')->name('login');
Route::get('auth-callback', 'Auth\LoginController@handleProviderCallback')->name('authCallback');

そして、設定値にも変更を加えます。まず、 config/services.php に下記を追加します。

<?php

return [

    // ... 中略 ...

    // ↓↓ ここから ↓↓
    'freeeaccounting' => [
        'client_id' => env('FREEE_ACCOUNTING_CLIENT_ID'),
        'client_secret' => env('FREEE_ACCOUNTING_CLIENT_SECRET'),
        'redirect' => 'http://localhost:8000/auth-callback',
    ],
    // ↑↑ ここまで編集 ↑↑
];

config/auth.php も更新します。

<?php

return [

    // ... 中略 ...

    'defaults' => [
        // ↓↓ ここから ↓↓
        // 'guard' => 'web',
        'guard' => 'freee',
        // ↑↑ ここまで編集 ↑↑
        'passwords' => 'users',
    ],

    // ... 中略 ...

    'guards' => [
        // ... 中略 ...

        // ↓↓ ここから ↓↓
        'freee' => [
            'driver' => 'freee',
            'provider' => 'freee',
        ],
        // ↑↑ ここまで追加 ↑↑
    ],

    // ... 中略 ...

    'providers' => [
        // ... 中略 ...

        // ↓↓ ここから ↓↓
        'freee' => [
            'driver' => 'freee',
        ],
        // ↑↑ ここまで追加 ↑↑
    ],

    // ... 略 ...

つぎに、 SocialiteProviders 配下のコードを少し修正します。

SocialiteProviders/src/FreeeAccounting/Provider.php

    protected function getUserByToken($token)
    {
        // ... 中略 ...

        // ↓↓ ここから ↓↓
        // return json_decode($response->getBody(), true);
        $body = json_decode($response->getBody(), true);
        return $body['user'];
        // ↑↑ ここまで編集 ↑↑
    }
    protected function mapUserToObject(array $user)
    {
        // ↓↓ ここから ↓↓
        $user['name'] = $user['last_name'] . ' ' . $user['first_name'];
        // ↑↑ ここまで追加 ↑↑

        return (new User())->setRaw($user)->map([
            'id'       => $user['id'],
            // 'nickname' => $user['username'],
            'name'     => $user['name'],
            'email'    => $user['email'],
            // 'avatar'   => $user['avatar'],
            // ↓↓ ここから ↓↓
            'display_name' => $user['display_name'],
            'first_name' => $user['first_name'],
            'last_name' => $user['last_name'],
            'first_name_kana' => $user['first_name_kana'],
            'last_name_kana' => $user['last_name_kana'],
            // ↑↑ ここまで追加 ↑↑
        ]);
    }

それでは、つぎにコントローラを整備しましょう。まず、 app\Http\Auth\LoginController.php を編集し、 会計freee API にログインできるようにします。

<?php

namespace App\Http\Controllers\Auth;

use App\Http\Controllers\Controller;
// ↓↓ ここから ↓↓
// use Illuminate\Foundation\Auth\AuthenticatesUsers;
use Illuminate\Auth\GenericUser;
use Illuminate\Support\Facades\Auth;
use Socialite;
// ↑↑ ここまで編集 ↑↑

class LoginController extends Controller
{
    /*
    |--------------------------------------------------------------------------
    | Login Controller
    |--------------------------------------------------------------------------
    |
    | This controller handles authenticating users for the application and
    | redirecting them to your home screen. The controller uses a trait
    | to conveniently provide its functionality to your applications.
    |
    */

    // ↓↓ ここから ↓↓
    // use AuthenticatesUsers;
    // ↑↑ ここまで編集 ↑↑

    /**
     * Where to redirect users after login.
     *
     * @var string
     */
    protected $redirectTo = '/home';

    /**
     * Create a new controller instance.
     *
     * @return void
     */
    public function __construct()
    {
        $this->middleware('guest')->except('logout');
    }

    // ↓↓ ここから ↓↓
    /**
     * Redirect the user to the Freee Accounting authentication page.
     *
     * @return \Illuminate\Http\Response
     */
    public function redirectToProvider()
    {
        return Socialite::driver('freeeaccounting')->redirect();
    }

    /**
     * Obtain the user information from Freee Accounting.
     *
     * @return \Illuminate\Http\Response
     */
    public function handleProviderCallback()
    {
        $user = Socialite::driver('freeeaccounting')->user();

        $genericUser = $user->getRaw();
        $genericUser['token'] = $user->token;
        $genericUser['remember_token'] = '';
        Auth::login(new GenericUser($genericUser));

        return redirect()->intended($this->redirectTo);
    }

    public function logout()
    {
        Auth::logout();
        return redirect()->intended('/');
    }
    // ↑↑ ここまで追加 ↑↑
}

つぎに、 app/Providers/AuthServiceProvider.php を下記のように編集します。

<?php

namespace App\Providers;

use Illuminate\Foundation\Support\Providers\AuthServiceProvider as ServiceProvider;
// ↓↓ ここから ↓↓
// use Illuminate\Support\Facades\Gate;
use App\Extensions\SampleSessionGuard;
use App\Extensions\FreeeUserProvider;
use Illuminate\Support\Facades\Auth;
// ↑↑ ここまで編集 ↑↑

class AuthServiceProvider extends ServiceProvider
{
    // ... 中略 ...

    /**
     * Register any authentication / authorization services.
     *
     * @return void
     */
    public function boot()
    {
        $this->registerPolicies();

        //

        // ↓↓ ここから ↓↓
        Auth::extend('freee', function ($app, $name, array $config) {
            return new SampleSessionGuard(
                $name,
                Auth::createUserProvider($config['provider']),
                $app['session.store']
            );
        });

        Auth::provider('freee', function ($app, array $config) {
            return new FreeeUserProvider();
        });
        // ↑↑ ここまで追加 ↑↑
    }
}

app/Providers/EventServiceProvider.php も下記のように編集します。

<?php

namespace App\Providers;

// ... 中略 ...

// ↓↓ ここから ↓↓
use SocialiteProviders\Manager\SocialiteWasCalled;
use SocialiteProviders\FreeeAccounting\FreeeAccountingExtendSocialite;
// ↑↑ ここまで追加 ↑↑

class EventServiceProvider extends ServiceProvider
{
    /**
     * The event listener mappings for the application.
     *
     * @var array
     */
    protected $listen = [
        Registered::class => [
            SendEmailVerificationNotification::class,
        ],
        // ↓↓ ここから ↓↓
        SocialiteWasCalled::class => [
            FreeeAccountingExtendSocialite::class,
        ],
        // ↑↑ ここまで追加 ↑↑
    ];

    // ... 略 ...
}

そして、 app/Extensions ディレクトリを作成し、このリポジトリの samples/BasicWebApp/app/Extensions 配下のすべてのファイルを、 app/Extensions にコピーします。

mkdir -p app/Extensions

# 前述のようにファイルをコピーする

ここまでの手順により、Laravel プロジェクトで会計freee APIにログインできるようになりました。

次に、本SDK を利用して情報を取得する部分も作成してみましょう。

情報を表示するための、コントローラー、ビューを作成します。まず、コントローラとして AccountController を作成しましょう。

php artisan make:controller AccountController

app/Http/Controllers/AccountController.php が作成されるので、そこに処理を記述します。

<?php

namespace App\Http\Controllers;

// ↓↓ ここから ↓↓
// use Illuminate\Http\Request;
use Freee\Accounting\Configuration;
use Freee\Accounting\Api\CompaniesApi;
use Freee\Accounting\Api\DealsApi;
use Illuminate\Support\Facades\Auth;
// ↑↑ ここまで編集 ↑↑

class AccountController extends Controller
{
    //

    // ↓↓ ここから ↓↓
    /**
     * Create a new controller instance.
     *
     * @return void
     */
    public function __construct()
    {
        $this->middleware('auth');
    }

    /**
     * Display information of current user.
     *
     * @return \Illuminate\View\View
     */
    public function me()
    {
        $user = Auth::user();

        $config = Configuration::getDefaultConfiguration()->setAccessToken($user->token);

        $companiesApiInstance = new CompaniesApi(null, $config);
        $companiesResponse = $companiesApiInstance->getCompanies();

        $dealsApiInstance = new DealsApi(null, $config);
        $targetCompanyId = $companiesResponse->getCompanies()[0]->getId();
        $limit = 5;
        $dealsResponse = $dealsApiInstance->getDeals(
            $targetCompanyId,
            null, null, null, null, null, null, null, null, null, null, null, null,
            $limit);
        $deals = $dealsResponse->getDeals();

        return view('account.me', compact('user', 'deals'));
    }
    // ↑↑ ここまで追加 ↑↑
}

そして、 AccountController にルーティングを通すために、 routes/web.php で下記を追記します。

Route::get('/account/me', 'AccountController@me')->name('me');

次にビューを用意しましょう。 resources/views/account ディレクトリを作成し、本リポジトリの samples/BasicWebApp/resources/views/account 配下のファイルをコピーします。

mkdir -p resources/views/account

# 前述のようにファイルをコピーする

作成したページへ遷移するメニューを追加しましょう。 resources/views/layouts/app.blade.php を下記のように更新します。

<!-- ... 中略 ... -->

<!-- Right Side Of Navbar -->
<ul class="navbar-nav ml-auto">
    <!-- Authentication Links -->
    @guest
        <li class="nav-item">
            <a class="nav-link" href="{{ route('login') }}">{{ __('Login') }}</a>
        </li>
        @if (Route::has('register'))
            <li class="nav-item">
                <a class="nav-link" href="{{ route('register') }}">{{ __('Register') }}</a>
            </li>
        @endif
    @else
        <li class="nav-item dropdown">
            <a id="navbarDropdown" class="nav-link dropdown-toggle" href="#" role="button" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false" v-pre>
                {{ Auth::user()->name }} <span class="caret"></span>
            </a>

            <div class="dropdown-menu dropdown-menu-right" aria-labelledby="navbarDropdown">
                <!-- ↓↓ ここから ↓↓ -->
                <a class="dropdown-item" href="{{ route('me') }}">
                    {{ __('Me') }}
                </a>
                <!-- ↑↑ ここまで追加 ↑↑ -->
                <a class="dropdown-item" href="{{ route('logout') }}"
                    onclick="event.preventDefault();
                                  document.getElementById('logout-form').submit();">
                    {{ __('Logout') }}
                </a>

<!-- ...... -->

ここで本手順は終わりです。 サンプルの実行方法 で示されるような動作が確認できれば導入成功です。

コントリビューションについて

このプロジェクトへのコントリビューションを歓迎いたします。詳細についてはコントリビューションガイドをご覧ください。

ライセンス

ライセンスについては下記をご参照ください。

MIT License

You can’t perform that action at this time.