Skip to content

Commit 428812f

Browse files
mideswebmidesweb
committed
update readme
1 parent 7492231 commit 428812f

1 file changed

Lines changed: 236 additions & 1 deletion

File tree

‎README.md‎

Lines changed: 236 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,238 @@
11
# Laravel Social Shareable
22

3-
Laravel Package to create shareable content in some social networks.
3+
[![Latest Version on Packagist](https://img.shields.io/packagist/v/escuelait/laravel-social-shareable.svg?style=flat-square)](https://packagist.org/packages/escuelait/laravel-social-shareable)
4+
[![Total Downloads](https://img.shields.io/packagist/dt/escuelait/laravel-social-shareable.svg?style=flat-square)](https://packagist.org/packages/escuelait/laravel-social-shareable)
5+
[![License](https://img.shields.io/packagist/l/escuelait/laravel-social-shareable.svg?style=flat-square)](LICENSE.md)
6+
7+
A Laravel package that makes it easy to generate sharing URLs for popular social networks. Share your content on X (Twitter), Facebook, WhatsApp, LinkedIn, Pinterest, Telegram, Email, Reddit, Bluesky, and Mastodon with just a few lines of code.
8+
9+
## Features
10+
11+
- 🚀 Generate sharing URLs for **10+ social networks**
12+
- 📱 Support for X, Facebook, WhatsApp, LinkedIn, Pinterest, Telegram, Email, Reddit, Bluesky, and Mastodon
13+
- 🎯 Simple and fluent API
14+
- 🔧 Easy to integrate with your models
15+
- ⚙️ Configurable (Facebook App ID support)
16+
- ✅ Fully tested
17+
- 🐘 PHP 8.1+ compatible
18+
- 🎗️ Laravel 10, 11, and 12 support
19+
20+
## Installation
21+
22+
You can install the package via Composer:
23+
24+
```bash
25+
composer require escuelait/laravel-social-shareable
26+
```
27+
28+
## Configuration
29+
30+
Publish the configuration file:
31+
32+
```bash
33+
php artisan vendor:publish --provider="Escuelait\SocialShareable\SocialShareableServiceProvider"
34+
```
35+
36+
Update your `.env` file with optional Facebook App ID:
37+
38+
```env
39+
FACEBOOK_APP_ID=your_facebook_app_id_here
40+
```
41+
42+
## Usage
43+
44+
### Using the Trait
45+
46+
Add the `SocialShareable` trait to your model:
47+
48+
```php
49+
<?php
50+
51+
namespace App\Models;
52+
53+
use Illuminate\Database\Eloquent\Model;
54+
use Escuelait\SocialShareable\SocialShareable;
55+
56+
class Post extends Model
57+
{
58+
use SocialShareable;
59+
60+
public $title = 'Check out this amazing post!';
61+
public $url = 'https://example.com/posts/1';
62+
}
63+
```
64+
65+
### Generating Share URLs
66+
67+
Generate share URLs for any social network:
68+
69+
```php
70+
$post = Post::first();
71+
72+
// Generate share URL for X (Twitter)
73+
$xUrl = $post->getShareUrl('x');
74+
75+
// Generate share URL for Facebook
76+
$facebookUrl = $post->getShareUrl('facebook');
77+
78+
// Generate share URL for WhatsApp
79+
$whatsappUrl = $post->getShareUrl('whatsapp');
80+
81+
// And more...
82+
$linkedinUrl = $post->getShareUrl('linkedin');
83+
$pinterestUrl = $post->getShareUrl('pinterest');
84+
$telegramUrl = $post->getShareUrl('telegram');
85+
$redditUrl = $post->getShareUrl('reddit');
86+
$blueskyUrl = $post->getShareUrl('bluesky');
87+
$mastodonUrl = $post->getShareUrl('mastodon');
88+
$emailUrl = $post->getShareUrl('email');
89+
```
90+
91+
### Custom Parameters
92+
93+
Pass custom parameters to override defaults:
94+
95+
```php
96+
$post = Post::first();
97+
98+
// Custom text for X with hashtags
99+
$xUrl = $post->getShareUrl('x', [
100+
'text' => 'Custom message with #hashtags',
101+
]);
102+
103+
// Custom URL for Facebook
104+
$facebookUrl = $post->getShareUrl('facebook', [
105+
'u' => 'https://custom-url.com',
106+
]);
107+
108+
// Custom quote for LinkedIn
109+
$linkedinUrl = $post->getShareUrl('linkedin', [
110+
'title' => 'Custom title for LinkedIn',
111+
]);
112+
```
113+
114+
### Resolving Title and URL
115+
116+
The trait looks for `$title` and `$url` properties on your model. You can customize this by overriding the resolution methods:
117+
118+
```php
119+
<?php
120+
121+
namespace App\Models;
122+
123+
use Illuminate\Database\Eloquent\Model;
124+
use Escuelait\SocialShareable\SocialShareable;
125+
126+
class Article extends Model
127+
{
128+
use SocialShareable;
129+
130+
protected function resolveShareUrl(): string
131+
{
132+
return route('articles.show', $this->slug);
133+
}
134+
135+
protected function resolveShareTitle(): string
136+
{
137+
return $this->headline ?? $this->title;
138+
}
139+
}
140+
```
141+
142+
## Supported Social Networks
143+
144+
The package supports the following social networks:
145+
146+
| Network | Method | Description |
147+
|---------|--------|-------------|
148+
| X (Twitter) | `x` | Share on X with custom text (max 120 chars) |
149+
| Facebook | `facebook` | Share on Facebook with quote and optional App ID |
150+
| WhatsApp | `whatsapp` | Share via WhatsApp with title and URL |
151+
| LinkedIn | `linkedin` | Share on LinkedIn with title |
152+
| Pinterest | `pinterest` | Share on Pinterest with description |
153+
| Telegram | `telegram` | Share via Telegram with text |
154+
| Email | `email` | Share via email with subject and body |
155+
| Reddit | `reddit` | Share on Reddit with title |
156+
| Bluesky | `bluesky` | Share on Bluesky with text |
157+
| Mastodon | `mastodon` | Share on Mastodon with text |
158+
159+
## Using the Generator Directly
160+
161+
You can also use the `SocialShareableGenerator` class directly without a model:
162+
163+
```php
164+
use Escuelait\SocialShareable\SocialShareableGenerator;
165+
166+
$generator = SocialShareableGenerator::for(
167+
'https://example.com',
168+
'Check this out!'
169+
);
170+
171+
$xUrl = $generator->x();
172+
$facebookUrl = $generator->facebook();
173+
$whatsappUrl = $generator->whatsapp();
174+
```
175+
176+
## View Components (Optional)
177+
178+
You can create Blade components to generate share buttons:
179+
180+
```blade
181+
<!-- resources/views/components/share-buttons.blade.php -->
182+
<div class="share-buttons">
183+
<a href="{{ $post->getShareUrl('x') }}" target="_blank" rel="noopener noreferrer">
184+
Share on X
185+
</a>
186+
<a href="{{ $post->getShareUrl('facebook') }}" target="_blank" rel="noopener noreferrer">
187+
Share on Facebook
188+
</a>
189+
<a href="{{ $post->getShareUrl('whatsapp') }}" target="_blank" rel="noopener noreferrer">
190+
Share on WhatsApp
191+
</a>
192+
<a href="{{ $post->getShareUrl('linkedin') }}" target="_blank" rel="noopener noreferrer">
193+
Share on LinkedIn
194+
</a>
195+
</div>
196+
```
197+
198+
## Testing
199+
200+
Run the test suite:
201+
202+
```bash
203+
composer test
204+
```
205+
206+
## Requirements
207+
208+
- PHP 8.1 or higher
209+
- Laravel 10, 11, or 12
210+
- illuminate/support package
211+
212+
## Changelog
213+
214+
See the [CHANGELOG](CHANGELOG.md) for recent changes.
215+
216+
## Contributing
217+
218+
Contributions are welcome! Please feel free to submit a pull request.
219+
220+
1. Fork the repository
221+
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
222+
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
223+
4. Push to the branch (`git push origin feature/amazing-feature`)
224+
5. Open a Pull Request
225+
226+
## License
227+
228+
This package is open-sourced software licensed under the [MIT license](LICENSE.md).
229+
230+
## Author
231+
232+
**Miguel Angel Alvarez**
233+
- Email: miguel@escuela.it
234+
- Website: [escuela.it](https://escuela.it)
235+
236+
## Credits
237+
238+
Created by [EscuelaIT](https://github.com/EscuelaIt)

0 commit comments

Comments
 (0)