MJExtension Deployment & Usage Guide

1. Prerequisites

• Xcode: Version 9.0 or later (for Swift 4+ compatibility)
• iOS/macOS Deployment Target: iOS 8.0+ or macOS 10.10+ (minimum supported by MJExtension)
• Dependency Manager (optional, if using automated installation):
  • CocoaPods 1.0+
  • Carthage 0.30+
  • Swift Package Manager (Xcode 11+)
• Swift Projects: Swift 4.0+ (due to @objc and dynamic requirements)

2. Installation

Choose one method:

CocoaPods

1. Add to your Podfile:

   pod 'MJExtension'
   

2. Install:

   pod install
   

Carthage

1. Add to your Cartfile:

   github "CoderMJLee/MJExtension"
   

2. Build:

   carthage update --platform iOS
   

3. Drag MJExtension.framework from Carthage/Build/iOS to your Xcode project's "Frameworks, Libraries, and Embedded Content" section.

Swift Package Manager (Xcode 11+)

1. In Xcode: File → Swift Packages → Add Package Dependency.
2. Enter repository URL: https://github.com/CoderMJLee/MJExtension
3. Select version (e.g., 3.4.0 or later) and add the package.

Manual Integration

1. Download or clone the repository.
2. Drag the entire MJExtension folder from the project root into your Xcode project (ensure "Copy items if needed" is checked).
3. Import the main header in any file using MJExtension:

   #import "MJExtension.h"
   

3. Configuration

Objective-C Models

No special configuration required for basic JSON ↔ model conversion. For custom behavior:

• Custom JSON Key Mapping: Override +mj_replacedKeyFromPropertyName in your model:

  @implementation User
  + (NSDictionary *)mj_replacedKeyFromPropertyName {
      return @{@"userID" : @"id"};
  }
  @end
  

• Date Formatting: Set a global date formatter block (e.g., in AppDelegate):

  [NSDateFormatter mj_setupDateFormatBlock:^NSString *(NSDateFormatter *formatter) {
      return @"yyyy-MM-dd HH:mm:ss";
  }];
  

Swift Models

Swift models require Objective-C runtime exposure:

1. Annotate the class with @objc or @objcMembers:

   @objcMembers
   class User: NSObject {
       // ...
   }
   

2. For non-optional primitive types (Bool, Int, Double, etc.), mark properties as dynamic and assign default values:

   dynamic var age: Int = 0
   dynamic var isVIP: Bool = false
   

3. Optional types (String?, Int?, etc.) do not require dynamic.

Core Data Integration

If using Core Data, register your entity:

[User mj_setupCoreDataEntity:^NSString *{
    return @"User";
}];

4. Build & Run

Building the Library (Only for Manual Integration or Development)

• Manual Integration: The library files are compiled directly into your app target—no separate build step needed.
• Developing MJExtension Itself: Open MJExtension.xcodeproj and build the MJExtension scheme.

Using MJExtension in Your Project

1. Create a model class (Objective-C or Swift as configured above).
2. Convert JSON to model:

   // Objective-C
   NSDictionary *json = @{@"name": @"Jack", @"age": @20};
   User *user = [User mj_objectWithKeyValues:json];
   

   // Swift
   let json: [String: Any] = ["name": "Jack", "age": 20]
   let user = User.mj_object(withKeyValues: json)
   

3. Convert model to JSON:

   NSDictionary *json = [user mj_keyValues];
   

4. For arrays:

   NSArray *userArray = [User mj_objectArrayWithKeyValuesArray:jsonArray];
   

5. Deployment

MJExtension is a static library/framework—it does not run standalone. To deploy an app using MJExtension:

1. Integrate MJExtension via one of the installation methods above.
2. Build your app for release (Product → Archive in Xcode).
3. Distribute via:
   • App Store Connect (iOS/macOS App Store)
   • Enterprise ad-hoc distribution
   • TestFlight (iOS)
   • Direct .ipa/.app distribution (enterprise or development)

No additional runtime dependencies are required—MJExtension is compiled into your app binary.

6. Troubleshooting

Swift Properties Not Converting

• Symptom: Swift model properties remain nil or default after JSON conversion.
• Solution:
  1. Ensure the class inherits from NSObject.
  2. Add @objc or @objcMembers to the class.
  3. Mark primitive types (Bool, Int, etc.) as dynamic with default values.
  4. Verify the JSON keys match property names (or use mj_replacedKeyFromPropertyName).

Date Conversion Fails

• Symptom: NSDate properties are nil or incorrect.
• Solution:
  1. Set a global date formatter block (see Configuration).
  2. For custom formats per property, implement +mj_objectClassInArray or use NSDateFormatter directly in a custom transformer.

Nested Models Not Populated

• Symptom: Model properties that are other models remain nil.
• Solution:
  1. Ensure nested model classes are imported (#import "NestedModel.h").
  2. Verify JSON structure matches property hierarchy exactly.
  3. For arrays of nested models, ensure the array property is typed as NSArray<NestedModel *> * or use +mj_objectClassInArray to specify the class.

JSON Key Mapping Not Applied

• Symptom: Custom key mapping (e.g., @"ID" : @"id") has no effect.
• Solution:
  1. Confirm +mj_replacedKeyFromPropertyName is implemented in the model implementation file (.m), not the header.
  2. Ensure the method returns a dictionary with JSON key as key and property name as value.

"Unrecognized Selector" Crashes

• Symptom: App crashes with NSInvalidArgumentException when calling mj_objectWithKeyValues.
• Solution:
  1. Verify the model class is linked (for manual integration, check the .m file is in the target's Compile Sources).
  2. For Swift, ensure the class is marked @objc and inherits from NSObject.

Carthage Framework Not Found

• Symptom: "Library not found for -lMJExtension" during build.
• Solution:
  1. Run carthage update --platform iOS again.
  2. Ensure the framework is added to "Linked Frameworks and Libraries" and "Embedded Binaries".
  3. Check that the framework search