salla/laravel-starter-kit

An awesome starter template to create your Salla Apps today! 🚀

3.0.0 2024-05-13 09:06 UTC

Requires

• php: ^7.3|^8.0
• fruitcake/php-cors: ^1.0
• guzzlehttp/guzzle: ^7.0.1
• inertiajs/inertia-laravel: ^1.0
• laravel/framework: ^11.0
• laravel/sanctum: ^4.0
• laravel/tinker: ^2.5
• laravel/ui: ^4.0
• lorisleiva/laravel-actions: ^2.1
• salla/ouath2-merchant: ^1.0
• tightenco/ziggy: ^1.0

Requires (Dev)

• fakerphp/faker: ^1.9.1
• laravel/breeze: ^2.0
• laravel/sail: ^1.0.1
• mockery/mockery: ^1.4.4
• nunomaduro/collision: ^8.1
• phpunit/phpunit: ^10.0
• spatie/laravel-ignition: ^2.0

MIT

• framework
• oauth2
• laravel
• salla

README

Salla Apps Starter Kit

An awesome starter template to create your Salla Apps today!
Explore our blogs »

Report Bug · Request Feature . </Salla Developers>

Table of Contents

1. Overview
2. Getting Started
   • Prerequisites
   • Installation
3. Usage
4. Configure Authorization Modes
   • Easy Mode
   • Custom Mode
5. Authorization Service
   • Refreshing a Token
6. Webhooks
   • Order Related Webhooks/Actions
   • Product Related Webhooks/Actions
   • Shipping Companies Related Webhooks/Actions
   • Customer Related Webhooks/Actions
   • Category Related Webhooks/Actions
   • Brand Related Webhooks/Actions
   • Store Related Webhooks/Actions
   • Cart Related Webhooks/Actions
   • Special Offer Related Webhooks/Actions
   • Miscellaneous Related Webhooks/Actions
7. Support
8. Contributing
9. License

Overview

This is a starter App includes a Laravel application equipped with the required auth processes and webhooks/actions that help you to create your Salla App which works with the Salla APIs. Your App later can be published to the Salla App Store and be available for installation to any of Salla Merchants Stores.

What can you use this starter App for?

• Create a Salla App from scratch, e.g. chatbot app or shipping service app, or any amazing app from your idea.
• Modify/Customize any of your previous Apps in order to take the advantages given by this starter App.

(back to top)

Getting Started

The starter App comes with an easy installation steps that do the complete setup for your starter App. To be ready, you will need some prerequisites which will be listed hereafter.

Prerequisites

Before proceeding with the installation, make sure you have the following prerequisites installed on your system:

• For Laravel compatibility: PHP >= 8.1, composer package manager, and MySql database.

• Dependency Managers: Node.js and Composer

• Web Server, PHP (>= 8.1), and MySQL

• Create a Partner account at Salla Partner Portal.

• Create a Salla App in your Partner account at Salla Partner Portal. This is to get the client-id and client-secret.

That is all!

Installation

The installation process is straightforward as you will see in the below steps.

1. Clone this Repo to your own localhost.
2. Install Dependencies: npm install and composer install
3. Generate an Application Key: php artisan key:generate
4. In your MySql Database: create a database with any name for example laravel.
5. Update the .env file.

(back to top)

Usage

First you need to create your App in Salla Partner Portal. This is to get the client-id and client-secret. For that you may use the Salla CLI.

Run the following command to create your App and follow on-screen instructions.:

salla app create

(back to top)

Important Note:

If you are using Easy mode. the access token will push to the action (app.store.authorize) via webhook

Output URLs

(back to top)

Configure Authorization Modes

While creating your App in the Salla Partners Portal, you will see that Salla provids two methods for the OAuth protocol, which are the Easy Mode and the Custom Mode.

During the setup process, the default OAuth protocol will be set to the Easy Mode, which can be configured from the file .env. All of the setup's values/keys are stored in the .env file as we can see in the below image.

Easy Mode

This mode is the default mode for the authorization, which means that the access token is generated automatically at Salla's side back to you. You may refer to the class StoreAuthorize which is defined inside app\Actions\App\StoreAuthorize.php to get more details on how to receive and manage the access token

Custom Mode

A callback Url is the Url that is triggered when the App has been granted authorization. This should be a valid Url to which the merchant's browser is redirected. In this mode, you will need to set a custom callback url from the App dashboard at the Salla Partner Portal. This callback url will redirect the merchants who are interested in using your app into your App entry page where the access token is generated. Moreover, using the Salla CLI command salla app serve, your callback url will be automatically updated.

You may refere to file app/Http/Controllers/OAuthController.php which contains the callback() function. This function is responsible for generating the access token

The custom url will redirect the merchant to the Store Dashboard in order to access the Store where he needs your App to be installed.

(back to top)

Authorization Service

This project comes with a simple singleton authorization service to help you with managing the access and refresh tokens

// set the current user or any user you want to use his access tokens
app('salla.auth')->forUser(auth()->user());

// Get the get the store details
/** Salla\OAuth2\Client\Provider\SallaUser::class **/
app('salla.auth')->getResourceOwner();

// Made an API request using the current access token of the user
app('salla.auth')->request('GET', 'https://api.salla.dev/admin/v2/products')['data'];
    
// Request a new access token
app('salla.auth')->getNewAccessToken();

// Save the access token
auth()->user()->token()->create([
    'merchant'      => 'id',
    'access_token'  => 'access token',
    'expires_in'    => 'expires in sec',
    'refresh_token' => 'refresh token'
]);

Refreshing a Token

Access tokens expire after two weeks. Once expired, you will have to refresh a user’s access token. you can easily request a new access token via the current refresh token for any user like this

try {
    // set the current user
    // or any user you want to refresh his access token
    app('salla.auth')
        ->forUser(auth()->user())
        ->getNewAccessToken();
    
    // by default the function `getNewAccessToken` will get a new access token 
    // and save the new access token to the same user you are set it in the `forUser` function
} catch (\League\OAuth2\Client\Provider\Exception\IdentityProviderException $exception) {
    // in case the token access token & refresh token is expired
    // you should redirect the user again to Salla authorization service to get a new token
    // return redirect()->route('oauth.redirect');
}

(back to top)

Webhooks

Webhooks simplify the communication between your App and Salla APIs. In this way, you will be notified whenever your app receives payload/data from the Salla APIs. These webhooks are triggered along with many actions such as an order or product being created, a customer logs in, a coupon is applied, and much more.

Create new Webhook/Action command

Salla already defined a list of the webhooks/actions that are triggered automatically. The predefined webhooks/actions can be found in the folder app/Actions.

Run the following command to create your webhook event:

salla app create-webhook <event.name>

You may find the supported Webhook events as follows:

Order Related Webhooks/Actions

(back to top)

Product Related Webhooks/Actions

(back to top)

Shipping Companies Related Webhooks/Actions

(back to top)

Customer Related Webhooks/Actions

(back to top)

Category Related Webhooks/Actions

(back to top)

Brand Related Webhooks/Actions

(back to top)

Store Related Webhooks/Actions

(back to top)

Cart Related Webhooks/Actions

(back to top)

Special Offer Related Webhooks/Actions

(back to top)

Miscellaneous Related Webhooks/Actions

(back to top)

Support

The team is always here to help you. Happen to face an issue? Want to report a bug? You can submit one here on Github using the Issue Tracker. If you still have any questions, please contact us via the Telegram Bot or join in the Global Developer Community on Telegram.

Contributing

Contributions are what make the open-source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

(back to top)

Security

If you discover any security-related issues, please email [e-mail] instead of using the issue tracker.

Credits

• Salla
• All Contributors

License

The MIT License (MIT). Please see License File for more information.

(back to top)