Share Your URL
==============

When you’re building an API locally, you often need to show it to teammates, clients or test webhooks from third-party services. LacePHP’s **Share** command uses ngrok to open a secure tunnel from the public internet to your local development server; no complex network setup required.

Why Share Your Local URL?
-------------------------
- **Instant demos**  
  Show your work in progress to stakeholders without deploying.  
- **Webhook testing**  
  Services like Stripe or GitHub need a public callback URL.  
- **Remote team collaboration**  
  Let colleagues access your local server from anywhere.

The `dev:share` Command
-----------------------
LacePHP provides a built-in command to start an ngrok tunnel:

.. code-block:: bash

   # Default (port 8000)
   php lace dev:share

   # Specify a different port (e.g. 6916)
   php lace dev:share 6916

What happens:

1. LacePHP echoes `Starting ngrok tunnel on port {port}…`  
2. Internally it calls `TunnelService($port)->share()`  
3. ngrok starts and prints a public URL, for example `https://abcd1234.ngrok.io`  
4. You can now access your local API at that public address.

Usage Example
-------------

1. **Start your local server**  
   In one terminal, run:

   .. code-block:: bash

      php lace tread

   You’ll see: `Server running at http://127.0.0.1:6916`

2. **Open the tunnel**  
   In another terminal:

   .. code-block:: bash

      php lace dev:share 6916

   You’ll get output similar to:

   .. code-block:: text

      Starting ngrok tunnel on port 6916...
      ngrok by @inconshreveable                                       (Ctrl+C to quit)
      Session Status                online
      Session Expires               7 hours, 59 minutes
      Version                       3.2.0
      Region                        United States (us)
      Web Interface                 http://127.0.0.1:4040
      Forwarding                    https://abcd1234.ngrok.io → http://localhost:6916

3. **Share the URL**  
   Copy the `https://abcd1234.ngrok.io` address and send it to your team or configure it for webhooks.

Under the Hood
--------------
The **TunnelService** class (in `Lacebox\Tongue\TunnelService`) wraps the ngrok binary:

- It spawns ngrok on the specified port  
- Captures and streams ngrok’s console output to your terminal  
- Manages the tunnel process until you press Ctrl+C  

Best Practices
--------------
- **Use only in development**—never expose your production database or secrets.  
- **Restrict access** with basic auth or IP allowlists if ngrok’s public URL is sensitive.  
- **Monitor usage**: tunnels are temporary and expire; ngrok’s dashboard (`http://127.0.0.1:4040`) shows active tunnels.  
- **Automate in scripts**: combine with `php lace tread` in a single shell script to start server and tunnel together.


.. warning::

   - Public tunnels mean anyone with the URL can hit your local machine—do not run with privileged or sensitive endpoints open.  
   - ngrok free plan limits concurrent tunnels and session duration—upgrade or use alternative tunneling tools if needed.  
   - Ensure your local environment matches production (env variables, database) before sharing for realistic testing.  

With `php lace dev:share`, you can quickly expose your local LacePHP apps; making demos, webhook tests and remote collaboration effortless.

|
|