This app uses a mysql database to store access tokens for registered stores generated by the BigCommerce API. As suggested in latest Laravel documentations, fastest and easiest way to setup your local development environment is to use Docker and Laravel Sail. Please refer to Official Laravel Documentation for getting your local machine ready for Laravel.

Laravel Installation
Sail

For other development environments, refer to official Laravel, PHP and mysql documentations to make adjustments accordingly.

1. Download the Repo and open in your code editor.
   a. If you are on a fresh computer with no php, Laravel or Sail configuration has ever done before; use below command to get Sail up and available.

   docker run --rm \
   -u "$(id -u):$(id -g)" \
   -v $(pwd):/opt \
   -w /opt \
   laravelsail/php80-composer:latest \
   composer install --ignore-platform-reqs
   

   Reference

2. Make a copy of .env.example and rename it .env

3. Add and start ngrok. Note: use port 80 to match Laravel app. - npm install ngrok - ngrok http 80 - Make note of your secure forwarding address (e.g. https://7865ec2cf4de.ngrok.io). 7865ec2cf4de is your ngrok_id for session duration.

   Keep ngrok open at all times, since your ngrok_id changes each time you start the app, if using unregistered or free.

4. Register a draft app with ngrok secure forwarding address.

   • For steps 5-7, enter callbacks as 'https://{ngrok_id}.ngrok.io/auth/{install||load||uninstall}'.
   • Get ngrok_id from the terminal that's running ngrok http 80.
   • e.g. auth callback URL: https://12345.ngrok.io/auth/install
   • e.g. load callback URL: https://12345.ngrok.io/auth/load
   • e.g. uninstall callback URL: https://12345.ngrok.io/auth/uninstall
   • For OAuth scopes in the Technical Tab, select Orders and Products as Modify and Information & Settings as Read-Only for now.

5. Copy ngrok secure forwarding address to following keys in .env

   • APP_URL
   • AUTH_CALLBACK

6. Replace client_id and client_secret in .env . Your BigCommerce Dev Portal (from View Client ID in the dev portal).

7. Run npm install and then npm run dev to compile frontend React code using Laravel Mix.

8. Run composer install to download and install laravel packages.

9. In a seperate terminal, run ./vendor/bin/sail up. After that, your docker app will be configured and ran along with multiple containers for app, db, etc.

10. In a seperate terminal, run ./vendor/bin/sail artisan migrate to initialize db tables.

11. Go to your Store Dashboard -> Apps -> My Apps -> My Draft Apps, you shall see your app on the page. Install the app.

12. If for some reason (such as new ngrok forwarding address etc.) you need to change env variables, clear env cache with command on a seperate terminal: ./vendor/bin/sail artisan config:cache

13. App uses cookie based session to pass over some data, also a mysql database configured in the laravel sail project to store access tokens for registered stores. access tokens currently are not hashed in the database.

If you run into trouble with your Laravel Docker Configuration, you can start from scratch by following these steps:

1. Remove all images and containers

./vendor/bin/sail down --rmi all -v

2. Recreate containers and start each one

./vendor/bin/sail up

3. Initialize Database

./vendor/bin/sail artisan migrate

• If you are pulling the new marketing updates (which requires onboards table on the db), don't forget to migrate. Or better yet, setup mysql database from fresh: (use command when sail is up)

./vendor/bin/sail artisan migrate:fresh

• For faster development in local machine, you can use local credentials. For that, you should set the following APP_ENV environment variable to local. This will cause the app to use the local API credentials:
  e.g. APP_ENV=local

• In order to work in local, you should also set store API credentials in the .env. You can generate API credentials in your store dashboard Advanced Settings->API Accounts->Create V2/V3 API Token (You need to select Information&Settings scope readonly and other scopes that you need for your app's functionality)

Below is an example of how these environment variables should look like.

# LOCAL
L_ACCESS_TOKEN=5ves21xef52y7kttyd0gm8c50yjy2zx
L_API_PATH=https://api.bigcommerce.com/stores/lrtom86d1e/v3/
L_CLIENT_ID=mbfav830kuwwr0toh07p4kppog5cco9
L_CLIENT_SECRET=b8d4c1ab541dee283b6871e96f2f96e6dc0610073acec6d650e4eeb197ad5a3f
L_STORE_HASH=stores/lrtom86d1e