Download the PHP package toolkito/larasap without Composer

👋 Introduction Laravel Social Auto Posting (Larasap)

Important Notice: This package has been moved from toolkito/larasap to alihesari/larasap. The old package is no longer maintained. Please use the new namespace for all future installations.

A powerful Laravel package that enables automated posting to multiple social media platforms including Telegram, X (Twitter), and Facebook. This package provides a simple and elegant way to manage your social media presence.

🔐 Authentication Methods

X (Twitter) API Authentication

This package uses OAuth 1.0a for X API authentication because:

• It's better suited for server-side automated posting
• Provides simpler implementation for Laravel applications
• No need to handle token refresh flows
• Works well with Laravel's configuration system

While X also supports OAuth 2.0, OAuth 1.0a is the recommended choice for this package's use case of automated server-side posting.

Facebook API Authentication

The package uses Facebook Graph API with Page Access Token for authentication. This provides:

• Secure access to Facebook Pages
• Long-lived tokens
• Granular permissions control
• Easy integration with Laravel's configuration system

Telegram Bot API Authentication

Uses Telegram Bot API token for authentication, providing:

• Simple token-based authentication
• Secure communication
• Easy setup process

🚀 Features

Telegram Features

• 📝 Send text messages
• 📷 Send photos with captions
• 🎵 Send audio files with metadata
• 📖 Send documents
• 📺 Send videos with metadata
• 🔊 Send voice messages
• 🎴 Send media groups (2-10 items)
• 📍 Send locations
• 📌 Send venues
• 📞 Send contacts
• 🌐 Send messages with inline keyboards
• ✏️ Edit messages and captions
• 📌 Pin/unpin messages
• 🔄 Message retry with backoff

X (Twitter) Features

• ✨ Send text tweets
• 🖼️ Send tweets with media (up to 4 items)
• 🗣️ Reply to tweets
• 💬 Quote tweets
• 📊 Create polls
• 📍 Add location to tweets
• ⏰ Schedule tweets
• 🔄 Rate limit handling
• 🔄 Automatic retry with backoff

Facebook Features

• 🔗 Share links with descriptions
• 📸 Post photos with captions
• 🎥 Share videos with titles and descriptions
• ⏰ Schedule posts
• 🔒 Privacy controls
• 🎯 Post targeting
• 📊 Debug mode
• 🔄 Error handling and logging

🔨 Installation

1. Install the package via Composer:

2. Publish the configuration file:

🔌 Configuration

Configure your social media credentials in config/larasap.php:

Detailed Configuration Guide

Telegram Configuration

• api_token: Your Telegram Bot API token from @BotFather
• bot_username: Your bot's username (without @)
• channel_username: Target channel username (without @)
• channel_signature: Text to be added at the end of each message
• proxy: Enable/disable proxy support (boolean)

X (Twitter) Configuration

• consumer_key: Your X API consumer key
• consumer_secret: Your X API consumer secret
• access_token: Your X API access token
• access_token_secret: Your X API access token secret

Facebook Configuration

• app_id: Your Meta App ID
• app_secret: Your Meta App Secret
• default_graph_version: Facebook Graph API version (default: v19.0)
• page_access_token: Your Facebook Page Access Token
• page_id: Your Facebook Page ID
• enable_beta_mode: Enable beta features (default: false)
• debug_mode: Enable detailed logging (default: false)

Environment Variables

You can also set these values in your .env file:

Configuration Validation

The package validates all configuration values on initialization. If any required values are missing or invalid, it will throw an exception with a descriptive message.

Configuration Caching

For better performance, the package caches the configuration values. If you need to refresh the configuration, you can clear the Laravel configuration cache:

🕹 Usage

First, add the following to your controller:

Telegram Examples

Basic Text Message

Text Message with Inline Keyboard

Send Photo with Caption

Send Audio File

Send Video with Thumbnail

Send Document

Send Location

X (Twitter) Examples

Basic Tweet

Tweet with Media

Reply to Tweet

Quote Tweet

Create Poll

Tweet with Location

Facebook Examples

Share Link with Custom Message

Share Photo with Caption

Share Video with Metadata

Share with Custom Privacy Settings

Share with Targeting

🔒 Security Features

• SSL verification enabled by default
• Proxy support with authentication
• Secure API token handling
• Rate limiting protection
• Input validation and sanitization
• Error handling with custom exceptions

⚡ Performance Features

• Connection timeout: 10 seconds
• Request timeout: 30 seconds
• Automatic JSON encoding/decoding
• Efficient cURL usage
• Retry mechanism with exponential backoff
• Rate limit handling

🧪 Testing

The package includes comprehensive test coverage:

• Unit tests for all components
• Feature tests for integration
• Mock responses for API calls
• Test mode for development

🧪 Testing Routes

To test the social media posting functionality, you can create your own routes in your Laravel application. Here's an example:

1. Create a controller:

2. Add the following code to your controller:

3. Add the route in your routes/web.php:

Now you can test the social media posting by visiting /test-social-posting in your browser.

Note: Make sure you have configured your social media credentials in config/larasap.php or your .env file before testing.

📝 Notes

• All methods support test mode for development
• Message length limits are enforced (4096 chars for text, 1024 for captions)
• Proxy configuration is optional but validated when provided
• Debug mode available for Facebook API
• Beta mode support for testing new features

🚩 Roadmap

• [ ] Improve test coverage
• [ ] Add support for more social media platforms
• [ ] Implement queue system for better performance
• [ ] Add support for story posting
• [ ] Implement analytics tracking
• [ ] Add support for carousel posts
• [ ] Implement bulk posting features

📄 License

This package is open-sourced software licensed under the MIT license.

License Terms

The MIT License is a permissive license that is short and to the point. It lets people do anything they want with your code as long as they provide attribution back to you and don't hold you liable.

What you can do with this package:

• ✅ Use it commercially
• ✅ Modify it
• ✅ Distribute it
• ✅ Use it privately
• ✅ Sublicense it

What you must do:

• ✅ Include the original copyright notice
• ✅ Include the license text

What you cannot do:

• ❌ Hold the author liable
• ❌ Use the author's name/trademarks without permission

Copyright Notice

Third-Party Licenses

This package uses several third-party libraries:

• dg/twitter-php - MIT License
• facebook/graph-sdk - MIT License
• illuminate/support - MIT License

For more information about third-party licenses, please see the composer.json file.

👥 Contributing

We welcome contributions to Laravel Social Auto Posting! Here's how you can help:

Development Setup

1. Fork the repository

2. Clone your fork:

3. Install dependencies:

4. Create a new branch for your feature:

Coding Standards

• Follow PSR-12 coding standards
• Add type hints and return types where possible
• Write meaningful commit messages following conventional commits
• Add tests for new features
• Update documentation for any changes

Testing

1. Run the test suite:

2. Run with coverage report:

Pull Request Process

1. Update the README.md with details of changes if needed
2. Update the CHANGELOG.md with your changes
3. The PR will be merged once you have the sign-off of at least one other developer

Commit Messages

• Use the present tense ("Add feature" not "Added feature")
• Use the imperative mood ("Move cursor to..." not "Moves cursor to...")
• Limit the first line to 72 characters or less
• Reference issues and pull requests liberally after the first line
• Consider starting the commit message with an applicable emoji:
  • 🎨 :art: when improving the format/structure of the code
  • 🐎 :racehorse: when improving performance
  • 🚱 :non-potable_water: when plugging memory leaks
  • 📝 :memo: when writing docs
  • 🐛 :bug: when fixing a bug
  • 🔥 :fire: when removing code or files
  • 💚 :green_heart: when fixing the CI build
  • ✅ :white_check_mark: when adding tests
  • 🔒 :lock: when dealing with security
  • ⬆️ :arrow_up: when upgrading dependencies
  • ⬇️ :arrow_down: when downgrading dependencies

Reporting Issues

• Use the issue tracker
• Describe the bug with a clear and descriptive title
• Include steps to reproduce the issue
• Include screenshots if applicable
• Include your environment details (PHP version, Laravel version, etc.)

Feature Requests

• Use the issue tracker
• Describe the feature with a clear and descriptive title
• Explain why this feature would be useful
• Include any relevant use cases

Security

• Report security issues to [email protected]
• Do not disclose security-related issues publicly until a fix has been announced

Code of Conduct

By participating in this project, you agree to abide by our Code of Conduct.

🤝 Support

If you encounter any issues or have questions, please open an issue on GitHub.

🛠 Development and Testing

Example Project

This package includes a Laravel 12 example project in the examples/laravel-12 directory that you can use for development and testing. This setup is particularly useful for:

• Testing new features
• Debugging issues
• Contributing to the package
• Understanding package usage
• Developing custom integrations

Setting Up the Development Environment

1. Clone the repository:

2. Set up the example project:

3. Configure your social media credentials in .env:

4. Link the package for development:

5. Start the development server:

Debugging

The example project includes VS Code debugging configurations in .vscode/launch.json for:

• Debugging the Laravel application
• Debugging the Larasap package
• Debugging Laravel tests

To use the debugger:

1. Install the PHP Debug extension in VS Code
2. Set breakpoints in your code
3. Select the appropriate debug configuration
4. Start debugging (F5)

Contributing

When contributing to the package:

1. Use the example project to test your changes
2. Ensure all tests pass
3. Follow the existing code style
4. Update documentation as needed
5. Submit a pull request with a clear description of your changes