# PROJECT PLANNER

A complete PHP/MySQL web application for managing multiple project workspaces with task tracking, workplan imports, and quarterly execution monitoring.

## 🚀 Features

- **Multi-User System**: Secure authentication with user registration and login
- **Project Workspaces**: Create and manage multiple isolated project environments
- **Workplan Import**: Upload CSV spreadsheets to automatically populate tasks
- **Task Management**: Track task status, priorities, deadlines, and deliverables
- **Progress Dashboard**: Visual statistics and completion tracking
- **Advanced Filtering**: Filter tasks by category, status, responsible party, and risk level
- **Activity Logging**: Complete audit trail of all user actions
- **Responsive Design**: Works seamlessly on desktop, tablet, and mobile devices

## 📋 Requirements

- **PHP**: 7.4 or higher
- **MySQL**: 5.6+ or MariaDB 10.0+
- **Web Server**: Apache (with mod_rewrite) or Nginx
- **cPanel**: For easy database and file management
- **File Upload**: Minimum 10MB support

## 🔧 Installation

### Quick Start (5 Minutes)

1. **Create Database**
   - Login to cPanel → MySQL Databases
   - Create database and user
   - Grant ALL PRIVILEGES

2. **Upload Files**
   - Extract all files to `public_html/project-planner/`
   - Set `uploads/` folder to 755 permissions

3. **Import Database**
   - cPanel → phpMyAdmin
   - Import `database_schema.sql`

4. **Configure Application**
   - Rename `config.example.php` to `config.php`
   - Edit database credentials
   - Set BASE_URL

5. **Access Application**
   - Visit: `https://yourdomain.com/project-planner/`
   - Default login: admin / admin123
   - **Change default password immediately!**

### Detailed Installation

See `INSTALLATION.txt` for comprehensive step-by-step instructions.

## 📖 User Guide

### Creating a Project

1. Login to your account
2. Click "New Project" button
3. Enter project details:
   - Project name
   - Description
   - Quarter (e.g., Q1 2026)
   - Deadline date
   - Target reach/metrics
4. **Optional**: Upload a workplan CSV file
5. Click "Create Project"

### Uploading Workplan Spreadsheets

**CSV Format Expected:**

```csv
Category,Task,Responsible,Due Date,Deliverable,Priority,Risk Level,Details
Infrastructure,Procure equipment,Project Coordinator,2026-01-17,All equipment procured,1,critical,Order laptops and tablets
Marketing,Create materials,Outreach Worker,2026-01-24,Materials developed,2,high,Design fliers and brochures
```

**Supported Columns:**
- Category / Type / Phase
- Task / Activity / Action
- Responsible / Owner / Assigned
- Due Date / Deadline / Completion Date
- Deliverable / Target / Output
- Priority (1-4)
- Risk Level (low/medium/high/critical)
- Details / Description / Notes
- Week / Timeline

The parser intelligently maps column headers, so exact naming isn't required.

### Managing Tasks

**Update Status:**
- Click the status dropdown on any task
- Select: Not Started → In Progress → Complete (or Blocked)
- Changes save automatically

**Filter Tasks:**
- Use filter bar to view specific categories, statuses, or responsible parties
- Combine multiple filters for precise views

**Add Tasks Manually:**
- Click "Add Task" button
- Fill in task details
- Submit to add to project

### Monitoring Progress

The dashboard shows:
- Total tasks and completion rate
- Tasks by status (completed, in progress, blocked)
- Days remaining until deadline
- Visual progress bars
- Task counts by priority

## 🎨 Customization

### Changing Colors

Edit `css/style.css` - modify CSS variables in `:root`:

```css
:root {
    --color-primary: #2563eb;      /* Primary blue */
    --color-success: #10b981;      /* Green */
    --color-danger: #ef4444;       /* Red */
    --color-warning: #f59e0b;      /* Orange */
}
```

### Adding Custom Fields

1. Add column to database:
```sql
ALTER TABLE tasks ADD COLUMN custom_field VARCHAR(255);
```

2. Update forms in `add-task.php` and `project.php`
3. Update CSV parser in `includes/spreadsheet-parser.php`

### Logo Customization

Edit `includes/header.php` and change:
```php
<span class="logo-icon">📋</span>
<span class="logo-text">Your Company Name</span>
```

## 🔒 Security

### Default Security Features

- Password hashing (bcrypt)
- SQL injection prevention (prepared statements)
- XSS protection (input sanitization)
- Session security (HttpOnly, Secure cookies)
- CSRF protection ready
- Activity logging
- File upload validation

### Security Checklist

- [ ] Change default admin password
- [ ] Set DEBUG_MODE to false
- [ ] Enable HTTPS
- [ ] Set proper file permissions
- [ ] Secure uploads folder
- [ ] Regular backups
- [ ] Update PHP regularly

## 📊 Database Structure

```
users            → User accounts
projects         → Project workspaces
tasks            → Project tasks
milestones       → Project milestones
deliverables     → Final deliverables
file_uploads     → Uploaded workplan files
activity_log     → Audit trail
```

## 🐛 Troubleshooting

### Database Connection Error

- Check credentials in `config.php`
- Verify database user has privileges
- Confirm database host (usually 'localhost')

### File Upload Failed

**Quick Diagnostic:**
- Run test_upload.php in your browser for instant diagnosis
- See UPLOAD_TROUBLESHOOTING.txt for comprehensive guide

**Common fixes:**
- Create uploads/ folder: `mkdir uploads && chmod 755 uploads`
- Check uploads/ folder permissions (should be 755)
- Increase PHP upload limits in `.htaccess`:
  ```
  php_value upload_max_filesize 20M
  php_value post_max_size 20M
  ```
- Use CSV format instead of Excel for better compatibility
- Download and try uploading sample_workplan.csv first

### Session Errors

- Clear browser cookies
- Check session folder permissions
- Verify session.save_path is writable

### 404 Errors

- Verify BASE_URL in `config.php`
- Ensure URL has trailing slash
- Check `.htaccess` file exists

## 📁 File Structure

```
project-planner/
├── css/
│   └── style.css              # Main stylesheet
├── js/
│   └── project.js             # Project page JavaScript
├── includes/
│   ├── header.php             # Site header
│   └── spreadsheet-parser.php # CSV/Excel parser
├── uploads/                    # User file uploads
├── config.example.php          # Configuration template
├── config.php                  # Your config (create from example)
├── database_schema.sql         # Database structure
├── .htaccess                   # Apache configuration
├── index.php                   # Entry point
├── login.php                   # Login page
├── register.php                # Registration
├── dashboard.php               # Project list
├── create-project.php          # New project form
├── project.php                 # Project detail view
├── add-task.php                # Manual task entry
├── logout.php                  # Logout script
├── INSTALLATION.txt            # Detailed install guide
└── README.txt                  # This file
```

## 🔄 Backup & Restore

### Database Backup

1. cPanel → phpMyAdmin
2. Select database
3. Export → Go
4. Save SQL file

### File Backup

1. cPanel → File Manager
2. Select `project-planner/` folder
3. Compress → Download

### Restore

1. Import SQL file in phpMyAdmin
2. Upload and extract backup files
3. Update `config.php` if needed

## 🚀 Future Enhancements

**Planned Features:**
- Excel (.xlsx) file support
- Email notifications
- PDF export
- Calendar view
- Gantt charts
- Team collaboration
- API integration
- Mobile app

## 💡 Tips & Best Practices

1. **Regular Backups**: Schedule daily database backups
2. **Clear Old Data**: Archive completed projects regularly
3. **Monitor Activity**: Review activity_log for unusual actions
4. **Update Regularly**: Keep PHP and MySQL updated
5. **Use Strong Passwords**: Enforce password complexity
6. **Enable HTTPS**: Always use SSL certificates
7. **Limit File Size**: Set appropriate upload limits
8. **Test Imports**: Verify CSV format before bulk uploads

## 📞 Support

For installation or configuration help:
1. Review `INSTALLATION.txt`
2. Check troubleshooting section above
3. Enable DEBUG_MODE for detailed errors
4. Consult your hosting provider

## 📝 License

This application is provided as-is for project management use.

## 🙏 Credits

Built with PHP, MySQL, and modern web standards.

---

**Version**: 1.0  
**Last Updated**: January 2026  
**Tested On**: PHP 7.4, 8.0, 8.1 | MySQL 5.7, 8.0 | cPanel WHM

---

**Quick Links:**
- [Detailed Installation Guide](INSTALLATION.txt)
- [Security Configuration](#security)
- [Troubleshooting](#troubleshooting)
- [Customization](#customization)

For the best experience, ensure your hosting meets all requirements and follow the security checklist before going live.
