# MTS Social Auto Post

![WordPress](https://img.shields.io/badge/WordPress-5.8%2B-blue.svg)
![PHP](https://img.shields.io/badge/PHP-7.4%2B-purple.svg)
![License](https://img.shields.io/badge/License-GPL%20v2-green.svg)
![Version](https://img.shields.io/badge/Version-1.0.0-orange.svg)

Automatically share your WordPress posts to your Facebook Page when you publish.

---

## Description

MTS Social Auto Post is a WordPress plugin that automatically shares your blog posts to your Facebook Page the moment you hit publish. No more manual copying and pasting, no more forgetting to share your content.

### Key Benefits

- **Save Time**: Automatically share posts without leaving WordPress
- **No Monthly Fees**: Unlike SaaS alternatives, this plugin is completely free
- **Full Control**: Your credentials stay on your server, encrypted
- **Reliable**: Built-in retry mechanism for failed posts

### Who Is This For?

- Bloggers who want to grow their Facebook audience
- Small businesses managing their own content
- Content creators who publish frequently
- Anyone tired of manually sharing posts to Facebook

---

## Features

| Feature | Description |
|---------|-------------|
| ✅ Auto-Post on Publish | Automatically share new posts when published |
| ✅ Manual Share Button | Share any post with one click from the post list |
| ✅ Customizable Templates | Use variables like `{title}`, `{excerpt}`, `{url}` |
| ✅ Featured Image Support | Include post thumbnails in Facebook shares |
| ✅ Category Filtering | Include or exclude specific categories |
| ✅ Multiple Post Types | Support for posts, pages, and custom post types |
| ✅ Scheduled Delay | Add a delay before sharing (1-60 minutes) |
| ✅ Post Log | Track all shares with status and timestamps |
| ✅ Automatic Retry | Failed posts automatically retry with exponential backoff |
| ✅ Bulk Share | Re-share existing posts in bulk |
| ✅ Token Expiry Warnings | Get notified before your token expires |
| ✅ Encrypted Storage | App Secret and Access Token stored securely |
| ✅ Setup Wizard | Easy 5-step configuration process |
| ✅ UTM Parameters | Track traffic with customizable UTM tags |
| ✅ Default Hashtags | Add consistent hashtags to all shares |

---

## Requirements

- WordPress 5.8 or higher
- PHP 7.4 or higher
- A Facebook Page (not a personal profile)
- A Facebook App (free to create)
- Facebook Business Manager account (for Page Access Token)

---

## Installation

### From GitHub

1. Download or clone this repository
2. Upload the `mts-social-auto-post` folder to `/wp-content/plugins/`
3. Activate the plugin through the **Plugins** menu in WordPress
4. Navigate to **Social Auto Post** in the admin menu
5. Complete the setup wizard

### From WordPress Admin

1. Download the latest release ZIP file
2. Go to **Plugins > Add New > Upload Plugin**
3. Choose the ZIP file and click **Install Now**
4. Activate the plugin
5. Complete the setup wizard

---

## Setup Guide

The plugin includes a step-by-step setup wizard, but here's an overview:

### 1. Create a Facebook App

1. Go to [Facebook Developers](https://developers.facebook.com/)
2. Click **My Apps > Create App**
3. Select **Business** type
4. Enter app name and contact email
5. Note your **App ID** and **App Secret**

### 2. Set Up Facebook Business Manager

1. Go to [Facebook Business Manager](https://business.facebook.com/)
2. Navigate to **Business Settings > Users > System Users**
3. Create a new System User with **Admin** role
4. Add your Facebook Page as an asset

### 3. Generate Page Access Token

1. In your System User settings, click **Generate Token**
2. Select your App
3. Select your Page
4. Grant these permissions:
   - `pages_manage_posts`
   - `pages_read_engagement`
   - `pages_show_list`
5. Copy the generated token

### 4. Configure the Plugin

1. Enter your App ID, App Secret, Page ID, and Access Token
2. Test the connection
3. Configure your post template and settings

For detailed instructions with screenshots, see the [Setup Documentation](docs/SETUP.md).

---

## Template Variables

Customize your Facebook post message using these variables:

| Variable | Description | Example Output |
|----------|-------------|----------------|
| `{title}` | Post title | "How to Bake Bread" |
| `{excerpt}` | Post excerpt or auto-generated | "Learn the basics of..." |
| `{content}` | Full post content (stripped) | "In this tutorial..." |
| `{url}` | Post permalink | "https://example.com/post" |
| `{short_url}` | Shortened URL | "https://example.com/?p=123" |
| `{author}` | Author display name | "John Doe" |
| `{date}` | Publish date | "January 15, 2025" |
| `{categories}` | Category names | "Recipes, Baking" |
| `{tags}` | Tag names | "bread, homemade, tutorial" |
| `{site_name}` | Site title | "My Awesome Blog" |
| `{site_url}` | Site home URL | "https://example.com" |

### Example Template

```
{title}

{excerpt}

Read more: {url}

#blogging #newpost
```

---

## Screenshots

### Dashboard
*Main dashboard showing share statistics and recent activity*

### Settings Page
*Configure auto-post options, templates, and Facebook credentials*

### Post Metabox
*Per-post controls for custom messages and sharing options*

### Post Log
*View all share attempts with status, timestamps, and retry options*

### Setup Wizard
*Guided 5-step configuration process*

---

## Frequently Asked Questions

### Do I need a Facebook App?

Yes. Facebook requires an App to post content via their API. Creating an App is free and takes about 10 minutes.

### Is this plugin free?

Yes, completely free with no premium version or upsells. Unlike SaaS services that charge monthly fees, this plugin runs entirely on your own server.

### Does the access token expire?

Yes, Page Access Tokens expire after approximately 60 days. The plugin displays warnings when your token is about to expire so you can refresh it in time.

### Can I share old posts?

Yes! Use the **Bulk Share** feature to select and share existing posts that weren't previously shared.

### Why did my post fail to share?

Common reasons include:
- Expired access token
- Missing permissions on the Facebook App
- Facebook API rate limits
- Network connectivity issues

Check the Post Log for specific error messages.

### Can I share to multiple Facebook Pages?

Currently, the plugin supports one Facebook Page per WordPress site. Multi-page support may be added in a future version.

### Does it work with custom post types?

Yes! You can enable any registered post type in the settings.

---

## Changelog

### 1.0.0 (January 2025)

**Initial Release**

- Auto-post to Facebook on publish
- Manual share from post list and edit screen
- Customizable post templates with variables
- Featured image support
- Category include/exclude filtering
- Multiple post type support
- Scheduled delay posting (1-60 minutes)
- Post log with status tracking
- Automatic retry with exponential backoff
- Bulk share for existing posts
- Token expiry warnings
- Encrypted credential storage
- 5-step setup wizard
- Dashboard widget
- UTM parameter support
- Default hashtags

---

## Contributing

We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

### Quick Start

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

### Reporting Bugs

Please use [GitHub Issues](https://github.com/AjeebBhai/mts-social-auto-post/issues) to report bugs. Include:
- WordPress version
- PHP version
- Steps to reproduce
- Expected vs actual behavior
- Error messages (if any)

---

## Security

Security is a top priority. If you discover a security vulnerability, please report it responsibly.

**Do not** open a public GitHub issue for security vulnerabilities.

Instead, email us at: **info@monirtechsolutions.com**

See [SECURITY.md](SECURITY.md) for our full security policy.

---

## License

This plugin is licensed under the GNU General Public License v2 or later.

```
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
```

See [LICENSE](LICENSE) for the full license text.

---

## Credits

Developed by **[Monir Tech Solutions](https://monirtechsolutions.com)**

- Website: [monirtechsolutions.com](https://monirtechsolutions.com)
- Documentation: [Plugin Docs](docs/)
- Support: [GitHub Issues](https://github.com/AjeebBhai/mts-social-auto-post/issues)

---

## Support

### Bug Reports & Feature Requests

Please use [GitHub Issues](https://github.com/AjeebBhai/mts-social-auto-post/issues) for:
- Bug reports
- Feature requests
- Technical questions

### General Support

For general questions or assistance:
- Email: info@monirtechsolutions.com
- Website: [monirtechsolutions.com](https://monirtechsolutions.com)

---

Made with ❤️ for the WordPress community