Introduction
- Example
Installation
Services
Contributing
Support Guidelines
- Community Driven Support
- Bugs, and Feature Prioritization
License - MIT License

Introduction

This package simplifies the process of adding share links to your Laravel application. Feel free to open a pull request if you notice we are missing a service!

A share link is a URL combining a social media base URL with query parameters for sharing content from your website or app. Parameters usually include the content URL and a preset message. These links, as shown in examples, let users easily share posts on platforms like Twitter, Facebook, and Telegram. Use this open-source package to quickly create share links via Laravel's blade component system.

Example

<x-link-sharer service="twitter" text="Share me!" url="https://www.defectivecode.com" hashtags="awesome,links" class="p-4">
    <!-- Your HTML code here to control the look and feel of the share button -->
    <span class="bg-blue-500 hover:bg-blue-700 text-white font-bold py-2 px-4 rounded">Click me!</span>
</x-link-sharer>

Installation

First install the PHP package by running the following composer command:
```
composer require defectivecode/link-sharer
```
That's it! Our package will automatically install using Laravel's package discovery.

Services

Service providers occasionally update their share links without prior notice. We make every effort to stay updated with these changes. However, if you encounter a non-functional service, kindly open an issue or submit a pull request. For adding a new service, refer to the contributing section below.

Some services provide extra parameters that can be passed to the component. These are documented in the table below.

Service	Text Supported	URL Supported	Notes
Blogger	✔️	✔️	`t` The text of the blog post.
Diaspora	✔️	✔️
Diigo	✔️	✔️	`description` A description to add to the post.
Douban	✔️	✔️	`comment` A commend to add to the post.
Evernote	✔️	✔️
Facebook	❌	✔️
Flipboard	✔️	✔️	`quote` A quote to add to the post.
Gmail	✔️	✔️	`bcc` A comma-separated list of email addresses to BCC. `cc` A comma-separated list of email addresses to CC. `su` The subject of the email. `to` A comma-separated list of email addresses to send to.
HackNews	✔️	✔️
Instapaper	✔️	✔️	`description` A description of the post.
LineMe	❌️	✔️
LinkedIn	❌	✔️
LiveJournal	✔️	✔️
Meneame	❌️	✔️
Okru	❌️	✔️
Outlook	✔️	✔️
Pinterest	✔️	✔️	`media` An image URL to show on the post.
Plurk	❌ ️	✔️
Pocket	✔️	✔️
QZone	✔️	✔️	`summary` A summary of the post.
Reddit	✔️	✔️
Renren	✔️	✔️	`description` A description of the post. `srcUrl` The original URL of the post.
Skype	✔️	✔️
Telegram	✔️	✔️
Threema	❌	✔️	`id` The id of the person to send the post.
Tumblr	✔️	✔️	`caption` A caption to add to the post. `tags` A comma seperated list of tags to apply to the post.
Twitter	✔️	✔️	`hastags` A comma seperated list of hash tags to apply to the tweet. `via` The tweeter to give credit to.
Viber	✔️	✔️
VKontakte	✔️	✔️	`description` A description of the post. `image` An image URL to show on the post.
Weibo	✔️	✔️
WhatsApp	✔️	✔️
Xing	❌	✔️
YahooMail	✔️	✔️

Contributing

Adding a service is relatively straightforward. Start by creating a new service class within the src/Services folder. Name the class after the service you're adding. The system automatically registers the service through the factory, so there's no need for manual registration.

The Gmail service provided below serves as a good example.

<?php
 
namespace DefectiveCode\LinkSharer\Services;
 
use DefectiveCode\LinkSharer\Traits\AppendsLinks;
 
class Gmail extends Service
{
    use AppendsLinks;
 
    protected string $baseUrl = 'https://mail.google.com/mail/u/0';
 
    protected array $baseParameterMapping = [
        'text' => 'body',
    ];
 
    protected array $additionalParameters = [
        'bcc',
        'cc',
        'su',
        'to',
    ];
 
    protected array $defaultParameters = [
        'view' => 'cm',
    ];
}

Please note that only the baseUrl is mandatory. The baseParameterMapping, additionalParameters, and defaultParameters are optional but can enhance functionality.

`$baseUrl`

A service's URL doesn't need to start with HTTPS. For instance, Viber uses viber://forward.

The baseUrl property specifies the service's primary URL. This URL is foundational when generating the share link, to which query parameters get appended. Using Gmail as an example, its base URL is https://mail.google.com/mail/u/0.

`$baseParameterMapping`

This package identifies two primary attributes: text and url, given their ubiquity across most service providers. Only define these attributes if the service in question employs a different naming convention. For instance, Gmail utilizes body in place of text, necessitating this explicit mapping. When using Gmail, any text attribute passed to the blade component gets transformed into the body query parameter in the share link.

`$additionalParameters`

Some services accept more specific query parameters. Taking Gmail as a reference, it supports bcc, cc, su, and to. Define these in the additionalParameters array. When users include these attributes in the blade component, they get added to the share link. Ensure these parameters are also listed in the supported services table, complete with concise descriptions.

`$defaultParameters`

Certain services mandate specific query parameters for the share link to function. As an example, Gmail necessitates the inclusion of view=cm. Such obligatory attributes are declared in the defaultParameters array. They always get appended to the share link and cannot be omitted.

`prepareAttributes()`

To manipulate the attributes before generating a share link, introduce a prepareAttributes method to your service. This method activates prior to passing attributes to the generateLink method, allowing for custom attribute modifications. Below is a demonstration using the AppendsLinks trait.

<?php
 
namespace DefectiveCode\LinkSharer\Traits;
 
trait AppendsLinks
{
    protected function prepareAttributes(): void
    {
        if (isset($this->attributes['text']) && isset($this->attributes['url'])) {
            $this->attributes['text'] = $this->attributes['text'] . "\n" . $this->attributes['url'];
            return;
        }
 
        if (isset($this->attributes['url'])) {
            $this->attributes['text'] = $this->attributes['url'];
        }
    }
}

Attributes passed into the service are accessible via the $attributes array. In the illustrated example:

If both text and url attributes are present, the url is appended to the text attribute.
Should only the url attribute be available, the text attribute assumes the value of the url.

Support Guidelines

Thanks for choosing our open source package! Please take a moment to check out these support guidelines. They'll help you get the most out of our project.

Community Driven Support

Our open-source project is fueled by our awesome community. If you have questions or need assistance, StackOverflow and other online resources are your best bets.

Bugs, and Feature Prioritization

The reality of managing an open-source project means we can't address every reported bug or feature request immediately. We prioritize issues in the following order:

1. Bugs Affecting Our Paid Products

Bugs that impact our paid products will always be our top priority. In some cases, we may only address bugs that affect us directly.

2. Community Pull Requests

If you've identified a bug and have a solution, please submit a pull request. After issues affecting our products, we give the next highest priority to these community-driven fixes. Once reviewed and approved, we'll merge your solution and credit your contribution.

3. Financial Support

For issues outside the mentioned categories, you can opt to fund their resolution. Each open issue is linked to an order form where you can contribute financially. We prioritize these issues based on the funding amount provided.

Community Contributions

Open source thrives when its community is active. Even if you're not fixing bugs, consider contributing through code improvements, documentation updates, tutorials, or by assisting others in community channels. We highly encourage everyone, as a community, to help support open-source work.

To reiterate, DefectiveCode will prioritize bugs based on how they impact our paid products, community pull requests, and the financial support received for issues.

License - MIT License

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

🔗Introduction

🔗Example

🔗Installation

🔗Services

🔗Contributing

🔗$baseUrl

🔗$baseParameterMapping

🔗$additionalParameters

🔗$defaultParameters

🔗prepareAttributes()

🔗Support Guidelines

🔗Community Driven Support

🔗Bugs, and Feature Prioritization