Download the PHP package freee/freee-accounting-sdk without Composer

このSDKはこれまで定期的にメンテナンスをしていましたが、2023年4月をもって定期的なメンテナンスを終了しました。 詳細は「freee会計 Public APIに関するSDKのメンテナンス終了、およびスキーマのymlファイルでの公開終了について」をご覧ください。

会計freee PHP SDK

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

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

このSDKは、リリースバージョンによって、内部で利用するAPIバージョンが異なります。

• 2.0.0 以降 - 会計freee APIの新しいAPIバージョン(v2020-06-15)に対応しています。
• 2.0.0 未満 - 会計freee APIの古いAPIバージョンを利用しています。古いAPIの提供終了に伴い、2020年12月以降に利用不可となります。

目次

• チュートリアル
  • 前提条件
  • 実行環境
  • freeeアプリストアへのアプリケーション登録
  • サンプルの実行方法
  • SDKの導入方法
• コントリビューションについて
• ライセンス

チュートリアル

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

前提条件

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

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

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

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

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

実行環境

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

• PHP 7.2 以上
• 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 7.x をベースに作成しています。サンプルを実行する際は、前述の実行環境に加え、下記も併せてご準備ください。

• PHP 7.2.5 以上
  • 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 を同梱しています。利用する際は、下記をご参考にご利用ください。

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

WebApp のサンプルの実行手順

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

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

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

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

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

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

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

Console のサンプル

Console のサンプルの実行環境 (Docker)

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

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

Console のサンプルの実行手順

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

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

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

SDKの導入方法

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

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

.env に下記を追加し、WebApp のサンプルの実行手順 に倣い <client_id>, <client-secret> を設定してください。

つぎに、データベースの設定を sqlite に変更します。 .env を下記のように編集します。 DB_DATABASE はプロジェクト内の database/database.sqlite への絶対パスを設定します。適宜調整してください。

つぎに、sqlite ファイルを作成し、マイグレーションを実行します。

作成したマイグレーションファイルを下記のように編集します。

app/User.php を編集します。

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

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

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

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

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

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

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

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

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

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

SocialiteProviders/src/FreeeAccounting/Provider.php

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

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

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

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

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

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

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

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

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

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

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

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

• 機能リクエスト
• 不具合報告
• プルリクエストの作成について

ライセンス

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

MIT License